docs: link community add-ons and forks

docs: move compressed result transfer guide out of README
feat(collector): optional compressed worker → master result transfer (#97 )
2026-10-12 01:20:46 +00:00 · 2026-10-11 20:55:37 +00:00 · 2026-10-11 20:50:23 +00:00 · 2026-10-11 10:06:41 +11:00 · 2026-10-10 16:00:41 -07:00 · 2026-10-10 16:00:36 -07:00
58 changed files with 5853 additions and 419 deletions
@@ -1,4 +1,3 @@
 # These are supported funding model platforms

 github: robertvoy
-buy_me_a_coffee: robertvoy
@@ -19,6 +19,6 @@ jobs:
      - name: Check out code
        uses: actions/checkout@v4
      - name: Publish Custom Node
-        uses: Comfy-Org/publish-node-action@v1
+        uses: Comfy-Org/publish-node-action@main
        with:
          personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}
@@ -15,7 +15,7 @@

 ---

-## Key Features
+## Key Features

 #### Parallel Workflow Processing
 - Run your workflow on multiple GPUs simultaneously with varied seeds, collect results on the master
@@ -27,22 +27,12 @@
 - Intelligent distribution
 - Handles single images and videos

-#### Ease of Use
- Auto-setup local workers; easily add remote/cloud ones
- Convert any workflow to distributed with 2 nodes
- JSON configuration with UI controls
-
---
-
-## Current Architecture
-
- Workflow-level load balancing is controlled by **Distributed Collector** via the `load_balance` toggle.
- There is **no Distributed Queue node** anymore.
- With `load_balance=true`, orchestration selects one least-busy execution participant:
-  - If master participation is enabled, master is included as a candidate.
-  - If master is in orchestrator-only mode, only workers are considered.
-
---
+#### Ease of Use
+- Auto-setup local workers; easily add remote/cloud ones
+- Convert any workflow to distributed with 2 nodes
+- JSON configuration with UI controls
+
+---

 ## Worker Types

@@ -61,7 +51,6 @@ ComfyUI Distributed supports three types of workers:
 ## Requirements

 - ComfyUI
-> Note: Desktop app not currently supported
 - Multiple NVIDIA GPUs
 > No additional GPUs? Use [Cloud Workers](https://github.com/robertvoy/ComfyUI-Distributed/blob/main/docs/worker-setup-guides.md#cloud-workers)
 - That's it
@@ -92,19 +81,19 @@ Join Runpod with [this link](https://get.runpod.io/0bw29uf3ug0p) and unlock a sp

 ## Workflow Examples

-### Basic Parallel Generation
-Generate multiple images in the time it takes to generate one. Each worker uses a different seed.
+### Basic Parallel Generation
+Generate multiple images in the time it takes to generate one. Each worker uses a different seed.

 ![Clipboard Image (6)](https://github.com/user-attachments/assets/9598c94c-d9b4-4ccf-ab16-a21398220aeb)

 > [Download workflow](/workflows/distributed-txt2img.json)

 1. Open your ComfyUI workflow
-2. Add **Distributed Seed** → connect to sampler's seed
-3. Add **Distributed Collector** → after VAE Decode
-4. Optional: enable `load_balance` on Distributed Collector to run on one least-busy participant
-5. Enable workers in the UI
-6. Run the workflow!
+2. Add **Distributed Seed** → connect to sampler's seed
+3. Add **Distributed Collector** → after VAE Decode
+4. Optional: enable `load_balance` on Distributed Collector to run on one least-busy participant
+5. Enable workers in the UI
+6. Run the workflow!

 ### Parallel WAN Generation
 Generate multiple videos in the time it takes to generate one. Each worker uses a different seed.
@@ -122,12 +111,12 @@ Generate multiple videos in the time it takes to generate one. Each worker uses
 7. Enable workers in the UI
 8. Run the workflow!

-### Distributed Image Upscaling
-Accelerate Ultimate SD Upscaler by distributing tiles across multiple workers, with speed scaling as you add more GPUs.
+### Distributed Image Upscaling
+Accelerate Ultimate SD Upscaler by distributing tiles across multiple workers, with speed scaling as you add more GPUs.

 ![Clipboard Image (3)](https://github.com/user-attachments/assets/ffb57a0d-7b75-4497-96d2-875d60865a1a)

-> [Download workflow](/workflows/distributed-upscale.json)
+> [Download workflow](/workflows/distributed-upscale.json)

 1. Load your image
 2. Upscale with ESRGAN or similar
@@ -153,40 +142,40 @@ Accelerate Ultimate SD Upscaler by distributing video tiles across multiple work

 ---

-## Developer API
+## Developer API

 Control your distributed cluster programmatically without opening the browser.

 * **Endpoint:** `POST /distributed/queue`
-* **Functionality:** Accepts a standard ComfyUI workflow JSON, automatically distributes it to available workers, and returns the execution ID.
+* **Functionality:** Accepts a ComfyUI API-format prompt, dispatches it to the requested reachable workers, and returns the master `prompt_id`.
 * **Documentation:** [See API Examples & Scripts](https://github.com/robertvoy/ComfyUI-Distributed/blob/main/docs/comfyui-distributed-api.md)

-> **⚠️ Security Warning:** Do not expose your ComfyUI port to the public internet. If you need remote access, run ComfyUI behind a secure proxy (like Cloudflare or a VPN).
-
---
-
-## Distributed Value
-
-Use **Distributed Value** when you want per-worker overrides (for example, different prompts/models/settings per worker).
-
- Output type adapts to the connected input where possible (`STRING`, `INT`, `FLOAT`, `COMBO`).
- The node shows only currently enabled workers.
- If worker enablement changes, worker fields update automatically.
- When disconnected, it resets to default string mode and clears per-worker overrides.
- On execution, master uses `default_value`; workers use their mapped override with typed coercion fallback to default.
-
---
-
-## Nodes
-
-| Node | Description |
-|------|-------------|
-| **Distributed Seed** | Generates unique seeds for each worker |
-| **Distributed Collector** | Collects results (image/video frames and optionally audio) from workers back to the master; `load_balance` can route the run to one least-busy participant |
-| **Distributed Value** | Outputs per-worker override values with fallback to default |
-| **Ultimate SD Upscale Distributed** | Distributes upscale tiles across workers |
-| **Image Batch Divider** | Splits image batches for multi-GPU output |
-| **Audio Batch Divider** | Splits audio batches for multi-GPU output |
+> **⚠️ Security Warning:** Do not expose your ComfyUI port to the public internet. If you need remote access, run ComfyUI behind a secure proxy (like Cloudflare or a VPN).
+
+---
+
+## Distributed Value
+
+Use **Distributed Value** when you want per-worker overrides (for example, different prompts/models/settings per worker).
+
+- Output type adapts to the connected input where possible (`STRING`, `INT`, `FLOAT`, `COMBO`).
+- The node shows only currently enabled workers.
+- If worker enablement changes, worker fields update automatically.
+- When disconnected, it resets to default string mode and clears per-worker overrides.
+- On execution, master uses `default_value`; workers use their mapped override with typed coercion fallback to default.
+
+---
+
+## Nodes
+
+| Node | Description |
+|------|-------------|
+| **Distributed Seed** | Generates unique seeds for each worker |
+| **Distributed Collector** | Collects results (image/video frames and optionally audio) from workers back to the master; `load_balance` can route the run to one least-busy participant |
+| **Distributed Value** | Outputs per-worker override values with fallback to default |
+| **Ultimate SD Upscale Distributed** | Distributes upscale tiles across workers |
+| **Image Batch Divider** | Splits image batches for multi-GPU output |
+| **Audio Segment Divider** | Splits an audio waveform into up to ten sequential time segments |
 | **Distributed Model Name** | Passes model paths to workers, enabling workflows to use models not present on the master in orchestrator-only mode |
 | **Distributed Empty Image** | Produces an empty IMAGE batch used when the master delegates all work |

@@ -206,7 +195,7 @@ No, it does not speed up the generation of a single image or video. Instead, it

 <details>
 <summary>Does it work with the ComfyUI desktop app?</summary>
-Currently, it is not compatible with the ComfyUI desktop app.
+Yes, it does now.
 </details>

 <details>
@@ -231,6 +220,26 @@ Yes, it is compatible with Docker setups, but you will need to configure your Do

 ---

+## Community projects
+
+Community-maintained add-ons and forks that extend ComfyUI-Distributed.
+
+### [ComfyUI-H3MC-Distributed](https://github.com/ymiyad/ComfyUI-H3MC-Distributed) by ymiyad
+
+Connects H3 Motion Context with ComfyUI-Distributed to generate multiple candidate takes of the next video clip across your workers. Compare the results, pick your preferred take, and use it as context for the next clip.
+
+Each saved candidate video includes its continuation latent, so you don't need a shared folder or separate latent files. This add-on speeds up iteration through parallel candidates; it does not split a single clip across GPUs.
+
+### [ComfyUI-Deadline-Distributed](https://github.com/doubletwisted/ComfyUI-Deadline-Distributed) by doubletwisted
+
+A fork of ComfyUI-Distributed with Thinkbox/AWS Deadline 10 integration for render farms. Claim Deadline workers from the Distributed panel, register them automatically, and collect their results back into your master workflow.
+
+Requires Deadline 10 and the author's ComfyUI-Deadline-Plugin.
+
+See each repository for installation instructions, requirements, and support.
+
+---
+
 ## Disclaimer

 This software is provided "as is" without any warranties, express or implied, including merchantability, fitness for a particular purpose, or non-infringement. The developers and copyright holders are not liable for any claims, damages, or liabilities arising from the use, modification, or distribution of the software. Users are solely responsible for ensuring compliance with applicable laws and regulations and for securing their networks against unauthorized access, hacking, data breaches, or loss. The developers assume no liability for any damages or incidents resulting from misuse, improper configuration, or external threats.
@@ -249,3 +258,4 @@ Buy me a coffee at: https://buymeacoffee.com/robertvoy



+
@@ -1,29 +1,22 @@
-# Import everything needed from the main module
-from .distributed import (
-    NODE_CLASS_MAPPINGS as DISTRIBUTED_CLASS_MAPPINGS, 
-    NODE_DISPLAY_NAME_MAPPINGS as DISTRIBUTED_DISPLAY_NAME_MAPPINGS
-)
+"""ComfyUI-Distributed's native V3 extension entrypoint."""
+from comfy_api.v0_0_2 import ComfyExtension, io

-# Import utilities
-from .utils.config import ensure_config_exists, CONFIG_FILE
-from .utils.logging import debug_log
+from .nodes.v3 import NODES
+from .runtime.bootstrap import initialize

-# Import distributed upscale nodes
-from .nodes.distributed_upscale import (
-    NODE_CLASS_MAPPINGS as UPSCALE_CLASS_MAPPINGS,
-    NODE_DISPLAY_NAME_MAPPINGS as UPSCALE_DISPLAY_NAME_MAPPINGS
-)
+WEB_DIRECTORY = './web'

-WEB_DIRECTORY = "./web"

-ensure_config_exists()
+class DistributedExtension(ComfyExtension):
+    async def on_load(self) -> None:
+        initialize()

-# Merge node mappings
-NODE_CLASS_MAPPINGS = {**DISTRIBUTED_CLASS_MAPPINGS, **UPSCALE_CLASS_MAPPINGS}
-NODE_DISPLAY_NAME_MAPPINGS = {**DISTRIBUTED_DISPLAY_NAME_MAPPINGS, **UPSCALE_DISPLAY_NAME_MAPPINGS}
+    async def get_node_list(self) -> list[type[io.ComfyNode]]:
+        return list(NODES)

-__all__ = ['NODE_CLASS_MAPPINGS', 'NODE_DISPLAY_NAME_MAPPINGS']

-debug_log("Loaded Distributed nodes.")
-debug_log(f"Config file: {CONFIG_FILE}")
-debug_log(f"Available nodes: {list(NODE_CLASS_MAPPINGS.keys())}")
+async def comfy_entrypoint() -> DistributedExtension:
+    return DistributedExtension()
+
+
+__all__ = ['comfy_entrypoint', 'WEB_DIRECTORY']
@@ -15,6 +15,7 @@ from ..utils.logging import debug_log
 from ..utils.image import pil_to_tensor, ensure_contiguous
 from ..utils.network import handle_api_error
 from ..utils.constants import JOB_INIT_GRACE_PERIOD, MEMORY_CLEAR_DELAY
+from ..utils import transfer_codec
 try:
    from .queue_orchestration import ensure_distributed_state, orchestrate_distributed_execution
 except ImportError:
@@ -26,8 +27,16 @@ from .queue_request import parse_queue_request_payload

 prompt_server = server.PromptServer.instance

-# Canonical worker result envelope accepted by POST /distributed/job_complete:
-# { "job_id": str, "worker_id": str, "batch_idx": int, "image": <base64 PNG>, "is_last": bool }
+# Worker result envelopes accepted by POST /distributed/job_complete:
+#
+# application/json (legacy, one frame per request):
+#   { "job_id": str, "worker_id": str, "batch_idx": int, "image": <base64 PNG>, "is_last": bool,
+#     "audio"?: {...} }
+#
+# multipart/form-data (compressed, many frames per request):
+#   envelope: JSON { "job_id", "worker_id", "format", "start_index", "count", "width", "height",
+#                    "is_last", "audio"?: {...} }
+#   media:    one part per frame for still formats, or one video file for video formats


 def _decode_image_sync(image_path):
@@ -217,7 +226,7 @@ async def distributed_queue_endpoint(request):
        return await handle_api_error(request, exc, 400)

    try:
-        prompt_id, worker_count = await orchestrate_distributed_execution(
+        prompt_id, prompt_number, worker_count, node_errors = await orchestrate_distributed_execution(
            payload.prompt,
            payload.workflow_meta,
            payload.client_id,
@@ -227,6 +236,8 @@ async def distributed_queue_endpoint(request):
        )
        return web.json_response({
            "prompt_id": prompt_id,
+            "number": prompt_number,
+            "node_errors": node_errors,
            "worker_count": worker_count,
            "auto_prepare_supported": True,
        })
@@ -268,8 +279,136 @@ async def check_file_endpoint(request):
        return await handle_api_error(request, e, 500)


+async def _enqueue_worker_items(multi_job_id, items):
+    """Put decoded items on the job queue, waiting briefly for the master to create it.
+
+    Returns the queue size after enqueueing, or None if the job never appeared.
+    """
+    deadline = time.monotonic() + float(JOB_INIT_GRACE_PERIOD)
+    while True:
+        async with prompt_server.distributed_jobs_lock:
+            pending = prompt_server.distributed_pending_jobs.get(multi_job_id)
+            if pending is not None:
+                for item in items:
+                    await pending.put(item)
+                return pending.qsize()
+        if time.monotonic() > deadline:
+            return None
+        await asyncio.sleep(0.05)
+
+
+def _decode_compressed_chunk_sync(envelope, parts):
+    """Decode a compressed chunk into per-frame IMAGE tensors (threadpool)."""
+    frames = transfer_codec.decode_chunk(envelope, parts)
+    return [
+        ensure_contiguous(torch.from_numpy(transfer_codec.uint8_frame_to_tensor_array(frame)))
+        for frame in frames
+    ]
+
+
+def _validate_compressed_envelope(envelope):
+    errors = []
+    if not isinstance(envelope, dict):
+        return ["envelope: expected JSON object"]
+    for key in ("job_id", "worker_id"):
+        value = envelope.get(key)
+        if not isinstance(value, str) or not value.strip():
+            errors.append(f"{key}: expected non-empty string")
+    start_index = envelope.get("start_index")
+    if not isinstance(start_index, int) or isinstance(start_index, bool) or start_index < 0:
+        errors.append("start_index: expected non-negative integer")
+    if not isinstance(envelope.get("is_last"), bool):
+        errors.append("is_last: expected boolean")
+    try:
+        if transfer_codec.normalize_format(envelope.get("format")) == transfer_codec.LEGACY_FORMAT:
+            errors.append("format: legacy_png must be sent as JSON")
+    except transfer_codec.TransferCodecError as exc:
+        errors.append(f"format: {exc}")
+    audio_payload = envelope.get("audio")
+    if audio_payload is not None and not isinstance(audio_payload, dict):
+        errors.append("audio: expected object when provided")
+    return errors
+
+
+async def _job_complete_compressed(request):
+    try:
+        form = await request.post()
+    except Exception as exc:
+        too_large = getattr(web, "HTTPRequestEntityTooLarge", None)
+        if too_large is not None and isinstance(exc, too_large):
+            return await handle_api_error(
+                request, f"Request body exceeds the master's upload limit (--max-upload-size): {exc}", 413)
+        return await handle_api_error(request, f"Invalid multipart payload: {exc}", 400)
+
+    raw_envelope = form.get("envelope")
+    if isinstance(raw_envelope, (bytes, bytearray)):
+        raw_envelope = raw_envelope.decode("utf-8")
+    elif hasattr(raw_envelope, "file"):
+        raw_envelope = raw_envelope.file.read().decode("utf-8")
+    try:
+        envelope = json.loads(raw_envelope) if isinstance(raw_envelope, str) else None
+    except ValueError as exc:
+        return await handle_api_error(request, f"envelope: invalid JSON ({exc})", 400)
+    if envelope is None:
+        return await handle_api_error(request, "envelope: missing field", 400)
+
+    errors = _validate_compressed_envelope(envelope)
+    if errors:
+        return await handle_api_error(request, errors, 400)
+
+    parts = []
+    for field in form.getall("media", []):
+        if hasattr(field, "file"):
+            parts.append(field.file.read())
+        elif isinstance(field, (bytes, bytearray)):
+            parts.append(bytes(field))
+        else:
+            return await handle_api_error(request, "media: expected binary file parts", 400)
+
+    loop = asyncio.get_running_loop()
+    try:
+        tensors = await loop.run_in_executor(None, _decode_compressed_chunk_sync, envelope, parts)
+        decoded_audio = _decode_audio_payload(envelope.get("audio")) if envelope.get("audio") is not None else None
+    except ValueError as exc:
+        return await handle_api_error(request, exc, 400)
+
+    multi_job_id = envelope["job_id"].strip()
+    worker_id = envelope["worker_id"].strip()
+    start_index = envelope["start_index"]
+    is_last = envelope["is_last"]
+    last_pos = len(tensors) - 1
+    items = [
+        {
+            "tensor": tensor,
+            "worker_id": worker_id,
+            "image_index": start_index + pos,
+            "is_last": bool(is_last and pos == last_pos),
+            "audio": decoded_audio if pos == last_pos else None,
+        }
+        for pos, tensor in enumerate(tensors)
+    ]
+
+    queue_size = await _enqueue_worker_items(multi_job_id, items)
+    if queue_size is None:
+        return await handle_api_error(request, "job not initialized", 404)
+
+    debug_log(
+        f"job_complete received {envelope['format']} chunk - job_id: {multi_job_id}, worker: {worker_id}, "
+        f"frames: {start_index}..{start_index + len(items) - 1}, "
+        f"bytes: {sum(len(p) for p in parts)}, is_last: {is_last}, queue_size: {queue_size}"
+    )
+    return web.json_response({"status": "success", "frames": len(items)})
+
+
@server.PromptServer.instance.routes.post("/distributed/job_complete")
 async def job_complete_endpoint(request):
+    content_type = str(getattr(request, "content_type", "") or "").lower()
+    if content_type.startswith("multipart/"):
+        try:
+            return await _job_complete_compressed(request)
+        except Exception as e:
+            return await handle_api_error(request, e)
+
    try:
        data = await request.json()
    except Exception as exc:
@@ -293,42 +432,41 @@ async def job_complete_endpoint(request):
            errors.append("worker_id: expected non-empty string")
        if not isinstance(batch_idx, int) or batch_idx < 0:
            errors.append("batch_idx: expected non-negative integer")
-        if not isinstance(image_payload, str) or not image_payload.strip():
+        image_provided = image_payload is not None
+        audio_provided = audio_payload is not None
+        if not image_provided and not audio_provided:
+            errors.append("expected at least one of image or audio")
+        if image_provided and (not isinstance(image_payload, str) or not image_payload.strip()):
            errors.append("image: expected non-empty base64 PNG string")
-        if audio_payload is not None and not isinstance(audio_payload, dict):
+        if audio_provided and not isinstance(audio_payload, dict):
            errors.append("audio: expected object when provided")
        if not isinstance(is_last, bool):
            errors.append("is_last: expected boolean")
        if errors:
            return await handle_api_error(request, errors, 400)

-        tensor = _decode_canonical_png_tensor(image_payload)
-        decoded_audio = _decode_audio_payload(audio_payload) if audio_payload is not None else None
+        try:
+            tensor = _decode_canonical_png_tensor(image_payload) if image_provided else None
+            decoded_audio = _decode_audio_payload(audio_payload) if audio_provided else None
+        except ValueError as exc:
+            return await handle_api_error(request, exc, 400)
        multi_job_id = job_id.strip()
        worker_id = worker_id.strip()

-        pending = None
-        queue_size = 0
-        deadline = time.monotonic() + float(JOB_INIT_GRACE_PERIOD)
-        while pending is None:
-            async with prompt_server.distributed_jobs_lock:
-                pending = prompt_server.distributed_pending_jobs.get(multi_job_id)
-                if pending is not None:
-                    await pending.put(
-                        {
-                            "tensor": tensor,
-                            "worker_id": worker_id,
-                            "image_index": int(batch_idx),
-                            "is_last": is_last,
-                            "audio": decoded_audio,
-                        }
-                    )
-                    queue_size = pending.qsize()
-                    break
-
-            if time.monotonic() > deadline:
-                return await handle_api_error(request, "job not initialized", 404)
-            await asyncio.sleep(0.05)
+        queue_size = await _enqueue_worker_items(
+            multi_job_id,
+            [
+                {
+                    "tensor": tensor,
+                    "worker_id": worker_id,
+                    "image_index": int(batch_idx),
+                    "is_last": is_last,
+                    "audio": decoded_audio,
+                }
+            ],
+        )
+        if queue_size is None:
+            return await handle_api_error(request, "job not initialized", 404)

        debug_log(
            f"job_complete received canonical envelope - job_id: {multi_job_id}, "
@@ -125,6 +125,209 @@ def _find_upstream_nodes(prompt_obj, start_ids):
    return connected


+_DELEGATE_MASTER_RETAINED_UPSTREAM_CLASSES = {
+    "PrimitiveBoolean",
+    "PrimitiveFloat",
+    "PrimitiveInt",
+    "PrimitiveNode",
+    "PrimitiveString",
+}
+
+_DELEGATE_MASTER_ALWAYS_RETAINED_UPSTREAM_CLASSES = {
+    "LoadImage",
+}
+
+_DELEGATE_MASTER_SAFE_SCALAR_TYPES = {"BOOLEAN", "FLOAT", "INT", "STRING"}
+_DELEGATE_MASTER_SAFE_LIST_TYPES = {"LIST"}
+
+# ComfyUI 0.23 exposes CreateList via the newer schema API rather than the
+# legacy RETURN_TYPES/INPUT_TYPES attributes. Treat it as a safe config utility
+# only after its connected inputs recursively prove safe.
+_DELEGATE_MASTER_SAFE_DYNAMIC_CONFIG_OUTPUT_CLASSES = {"CreateList"}
+_DELEGATE_MASTER_SAFE_DYNAMIC_CONFIG_INPUT_PREFIXES = {
+    "CreateList": ("inputs.",),
+}
+
+# Test hook. At runtime this stays None and the ComfyUI node registry is loaded lazily.
+_DELEGATE_MASTER_NODE_CLASS_MAPPINGS = None
+
+
+def _get_delegate_master_node_class_mappings():
+    """Return ComfyUI node-class mappings when available."""
+    if _DELEGATE_MASTER_NODE_CLASS_MAPPINGS is not None:
+        return _DELEGATE_MASTER_NODE_CLASS_MAPPINGS
+    try:
+        import nodes as comfy_nodes  # type: ignore
+    except Exception:  # pragma: no cover - depends on ComfyUI runtime imports
+        return {}
+    return getattr(comfy_nodes, "NODE_CLASS_MAPPINGS", {}) or {}
+
+
+def _get_delegate_master_node_class(class_type):
+    mappings = _get_delegate_master_node_class_mappings()
+    return mappings.get(class_type) if isinstance(mappings, dict) else None
+
+
+def _normalize_delegate_master_return_type(return_type):
+    if return_type is None:
+        return ""
+    return str(return_type).strip().upper()
+
+
+def _delegate_master_type_is_safe_scalar(type_name):
+    return type_name in _DELEGATE_MASTER_SAFE_SCALAR_TYPES
+
+
+def _delegate_master_type_is_safe_config(type_name):
+    return _delegate_master_type_is_safe_scalar(type_name) or type_name in _DELEGATE_MASTER_SAFE_LIST_TYPES
+
+
+def _delegate_master_output_is_safe_scalar(class_type, output_index):
+    """Return True when a registered node output is lightweight config data."""
+    if class_type in _DELEGATE_MASTER_SAFE_DYNAMIC_CONFIG_OUTPUT_CLASSES:
+        return True
+    node_class = _get_delegate_master_node_class(class_type)
+    return_types = getattr(node_class, "RETURN_TYPES", ()) if node_class is not None else ()
+    try:
+        output_type = return_types[int(output_index)]
+    except (IndexError, TypeError, ValueError):
+        return False
+    return _delegate_master_type_is_safe_config(_normalize_delegate_master_return_type(output_type))
+
+
+def _get_delegate_master_input_types(class_type):
+    node_class = _get_delegate_master_node_class(class_type)
+    input_types = getattr(node_class, "INPUT_TYPES", None) if node_class is not None else None
+    if callable(input_types):
+        try:
+            input_types = input_types()
+        except TypeError:
+            return {}
+    return input_types if isinstance(input_types, dict) else {}
+
+
+def _normalize_delegate_master_input_type(input_spec):
+    if isinstance(input_spec, (list, tuple)) and input_spec:
+        return _normalize_delegate_master_return_type(input_spec[0])
+    return _normalize_delegate_master_return_type(input_spec)
+
+
+def _delegate_master_input_is_safe_scalar(class_type, input_name):
+    """Return True when a registered downstream input expects config data."""
+    for prefix in _DELEGATE_MASTER_SAFE_DYNAMIC_CONFIG_INPUT_PREFIXES.get(class_type, ()):
+        if input_name.startswith(prefix):
+            return True
+    input_types = _get_delegate_master_input_types(class_type)
+    for section_name in ("required", "optional"):
+        section = input_types.get(section_name, {})
+        if isinstance(section, dict) and input_name in section:
+            input_type = _normalize_delegate_master_input_type(section[input_name])
+            return _delegate_master_type_is_safe_config(input_type)
+    return False
+
+
+def _is_delegate_master_always_retained_upstream_node(node):
+    if not isinstance(node, dict):
+        return False
+    class_type = node.get("class_type")
+    return isinstance(class_type, str) and class_type in _DELEGATE_MASTER_ALWAYS_RETAINED_UPSTREAM_CLASSES
+
+
+def _is_delegate_master_retained_upstream_node(node, output_index=0):
+    """Return True for lightweight upstream nodes safe to keep on the master."""
+    if not isinstance(node, dict):
+        return False
+    class_type = node.get("class_type")
+    if not isinstance(class_type, str):
+        return False
+    return (
+        class_type in _DELEGATE_MASTER_RETAINED_UPSTREAM_CLASSES
+        or class_type.startswith("Primitive")
+        or _delegate_master_output_is_safe_scalar(class_type, output_index)
+    )
+
+
+def _collect_delegate_master_retained_upstream_branch(
+    prompt_obj,
+    node_id,
+    output_index,
+    memo,
+    visiting,
+):
+    """Return safe retained branch nodes, or None when the branch is not safe."""
+    node_id = str(node_id)
+    cache_key = (node_id, output_index)
+    if cache_key in memo:
+        cached = memo[cache_key]
+        return None if cached is None else set(cached)
+    if cache_key in visiting:
+        memo[cache_key] = None
+        return None
+
+    node = prompt_obj.get(node_id)
+    if not _is_delegate_master_retained_upstream_node(node, output_index):
+        memo[cache_key] = None
+        return None
+
+    visiting.add(cache_key)
+    retained = {node_id}
+    inputs = node.get("inputs", {}) if isinstance(node, dict) else {}
+    class_type = node.get("class_type") if isinstance(node, dict) else None
+    for input_name, value in inputs.items():
+        if not (isinstance(value, list) and len(value) == 2):
+            continue
+        if not _delegate_master_input_is_safe_scalar(class_type, input_name):
+            visiting.remove(cache_key)
+            memo[cache_key] = None
+            return None
+        source_id = str(value[0])
+        branch = _collect_delegate_master_retained_upstream_branch(
+            prompt_obj,
+            source_id,
+            value[1],
+            memo,
+            visiting,
+        )
+        if branch is None:
+            visiting.remove(cache_key)
+            memo[cache_key] = None
+            return None
+        retained.update(branch)
+
+    visiting.remove(cache_key)
+    memo[cache_key] = frozenset(retained)
+    return retained
+
+
+def _find_delegate_master_retained_upstream_nodes(prompt_obj, start_ids):
+    """Return lightweight upstream nodes needed by kept delegate-master nodes."""
+    connected = set()
+    memo = {}
+    for node_id in start_ids:
+        node = prompt_obj.get(str(node_id)) or {}
+        inputs = node.get("inputs", {})
+        class_type = node.get("class_type") if isinstance(node, dict) else None
+        for input_name, value in inputs.items():
+            if not (isinstance(value, list) and len(value) == 2):
+                continue
+            source_node = prompt_obj.get(str(value[0]))
+            if _is_delegate_master_always_retained_upstream_node(source_node):
+                connected.add(str(value[0]))
+                continue
+            if not _delegate_master_input_is_safe_scalar(class_type, input_name):
+                continue
+            branch = _collect_delegate_master_retained_upstream_branch(
+                prompt_obj,
+                value[0],
+                value[1],
+                memo,
+                set(),
+            )
+            if branch is not None:
+                connected.update(branch)
+    return connected
+
+
 def prune_prompt_for_worker(prompt_obj):
    """Prune worker prompt to distributed nodes and their upstream dependencies."""
    collector_ids = find_nodes_by_class(prompt_obj, "DistributedCollector")
@@ -148,16 +351,33 @@ def prune_prompt_for_worker(prompt_obj):
        downstream = _find_downstream_nodes(prompt_obj, [dist_id])
        has_removed_downstream = any(node_id != dist_id for node_id in downstream)
        if has_removed_downstream:
-            preview_id = next_id()
-            pruned_prompt[preview_id] = {
-                "inputs": {
-                    "images": [dist_id, 0],
-                },
-                "class_type": "PreviewImage",
-                "_meta": {
-                    "title": "Preview Image (auto-added)",
-                },
-            }
+            original_node = prompt_obj.get(str(dist_id), {})
+            class_type = original_node.get("class_type")
+            inputs = original_node.get("inputs", {})
+            image_connected = class_type != "DistributedCollector" or (
+                isinstance(inputs.get("images"), list)
+                and len(inputs["images"]) == 2
+            )
+            audio_connected = (
+                class_type == "DistributedCollector"
+                and isinstance(inputs.get("audio"), list)
+                and len(inputs["audio"]) == 2
+            )
+
+            if image_connected:
+                preview_id = next_id()
+                pruned_prompt[preview_id] = {
+                    "inputs": {"images": [dist_id, 0]},
+                    "class_type": "PreviewImage",
+                    "_meta": {"title": "Preview Image (auto-added)"},
+                }
+            elif audio_connected:
+                preview_id = next_id()
+                pruned_prompt[preview_id] = {
+                    "inputs": {"audio": [dist_id, 1]},
+                    "class_type": "PreviewAudio",
+                    "_meta": {"title": "Preview Audio (auto-added)"},
+                }

    return pruned_prompt

@@ -167,6 +387,9 @@ def prepare_delegate_master_prompt(prompt_obj, collector_ids):
    downstream = _find_downstream_nodes(prompt_obj, collector_ids)
    nodes_to_keep = set(collector_ids)
    nodes_to_keep.update(downstream)
+    nodes_to_keep.update(
+        _find_delegate_master_retained_upstream_nodes(prompt_obj, nodes_to_keep)
+    )

    pruned_prompt = {}
    for node_id in nodes_to_keep:
@@ -194,6 +417,10 @@ def prepare_delegate_master_prompt(prompt_obj, collector_ids):
        collector_entry = pruned_prompt.get(collector_id)
        if not collector_entry:
            continue
+        original_inputs = (prompt_obj.get(collector_id) or {}).get("inputs", {})
+        original_images = original_inputs.get("images")
+        if not (isinstance(original_images, list) and len(original_images) == 2):
+            continue
        placeholder_id = next_id()
        pruned_prompt[placeholder_id] = {
            "class_type": "DistributedEmptyImage",
@@ -13,7 +13,7 @@ from ..utils.constants import (
    ORCHESTRATION_WORKER_PREP_CONCURRENCY,
 )
 from ..utils.logging import debug_log, log
-from ..utils.network import build_master_url
+from ..utils.network import build_master_url, build_master_callback_url
 from ..utils.trace_logger import trace_debug
 from .schemas import parse_positive_float, parse_positive_int
 from .orchestration.dispatch import (
@@ -144,6 +144,7 @@ async def _prepare_worker_payload(
    enabled_ids,
    job_id_map,
    master_url,
+    config,
    delegate_master,
    trace_execution_id,
    worker_prep_semaphore,
@@ -153,6 +154,11 @@ async def _prepare_worker_payload(
    """Prepare one worker prompt payload with bounded concurrency and media-sync timeout."""
    async with worker_prep_semaphore:
        worker_prompt = prompt_index.copy_prompt()
+        worker_master_url = build_master_callback_url(
+            worker,
+            config=config,
+            prompt_server_instance=prompt_server,
+        )

        worker_type = str(worker.get("type") or "local").strip().lower()
        is_remote_like = bool(worker.get("host")) and worker_type != "local"
@@ -167,7 +173,7 @@ async def _prepare_worker_payload(
            worker["id"],
            enabled_ids,
            job_id_map,
-            master_url,
+            worker_master_url,
            delegate_master,
            prompt_index,
        )
@@ -202,7 +208,7 @@ async def orchestrate_distributed_execution(
    """Core orchestration logic for the /distributed/queue endpoint.

    Returns:
-        tuple[str, int]: (prompt_id, worker_count)
+        tuple[str, int, int, dict]: (prompt_id, number, worker_count, node_errors)
    """
    ensure_distributed_state()
    execution_trace_id = trace_execution_id or _generate_execution_trace_id()
@@ -311,8 +317,18 @@ async def orchestrate_distributed_execution(

    if not job_id_map:
        trace_debug(execution_trace_id, "No distributed nodes detected; queueing prompt on master only.")
-        prompt_id = await queue_prompt_payload(prompt_obj, workflow_meta, client_id)
-        return prompt_id, 0
+        queue_result = await queue_prompt_payload(
+            prompt_obj,
+            workflow_meta,
+            client_id,
+            include_queue_metadata=True,
+        )
+        return (
+            queue_result["prompt_id"],
+            queue_result["number"],
+            0,
+            queue_result.get("node_errors", {}),
+        )

    for job_id in job_id_map.values():
        await _ensure_distributed_queue(job_id)
@@ -360,6 +376,7 @@ async def orchestrate_distributed_execution(
                    enabled_ids,
                    job_id_map,
                    master_url,
+                    config,
                    delegate_master,
                    execution_trace_id,
                    worker_prep_semaphore,
@@ -385,9 +402,17 @@ async def orchestrate_distributed_execution(
            ]
        )

-    prompt_id = await queue_prompt_payload(master_prompt, workflow_meta, client_id)
+    queue_result = await queue_prompt_payload(
+        master_prompt,
+        workflow_meta,
+        client_id,
+        include_queue_metadata=True,
+    )
+    prompt_id = queue_result["prompt_id"]
+    prompt_number = queue_result["number"]
+    node_errors = queue_result.get("node_errors", {})
    trace_debug(
        execution_trace_id,
        f"Orchestration complete: prompt_id={prompt_id}, dispatched_workers={len(worker_payloads)}, delegate_master={delegate_master}",
    )
-    return prompt_id, len(worker_payloads)
+    return prompt_id, prompt_number, len(worker_payloads), node_errors
@@ -16,12 +16,14 @@ from ..utils.logging import debug_log, log
 from ..utils.network import (
    build_worker_url,
    get_client_session,
+    get_server_port,
    handle_api_error,
    normalize_host,
    probe_worker,
 )
 from ..utils.constants import CHUNK_SIZE
 from ..workers import get_worker_manager
+from ..workers.ports import allocate_worker_ports
 from .schemas import require_fields, validate_worker_id
 from ..workers.detection import (
    get_machine_id,
@@ -277,6 +279,13 @@ def _get_cuda_info():
 def _collect_network_info_sync():
    """Collect network/cuda info in a worker thread to avoid blocking route handlers."""
    cuda_device, cuda_device_count, physical_device_count = _get_cuda_info()
+    device_count = physical_device_count if physical_device_count > 0 else cuda_device_count
+    master_port = get_server_port()
+    config = load_config()
+    worker_ports = []
+    if not config.get("settings", {}).get("has_auto_populated_workers") and not config.get("workers"):
+        worker_count = device_count - (1 if cuda_device is not None and 0 <= cuda_device < device_count else 0)
+        worker_ports = allocate_worker_ports(master_port, config.get("workers", []), worker_count)
    hostname = socket.gethostname()
    all_ips = get_network_ips()
    recommended_ip = get_recommended_ip(all_ips)
@@ -285,7 +294,9 @@ def _collect_network_info_sync():
        "all_ips": all_ips,
        "recommended_ip": recommended_ip,
        "cuda_device": cuda_device,
-        "cuda_device_count": physical_device_count if physical_device_count > 0 else cuda_device_count,
+        "cuda_device_count": device_count,
+        "master_port": master_port,
+        "local_worker_ports": worker_ports,
    }


@@ -483,6 +494,8 @@ async def launch_worker_endpoint(request):
                "message": f"Worker {worker['name']} launched",
                "log_file": log_file
            })
+        except ValueError as e:
+            return await handle_api_error(request, f"Failed to launch worker: {str(e)}", 400)
        except Exception as e:
            return await handle_api_error(request, f"Failed to launch worker: {str(e)}", 500)
            
@@ -1,7 +1,7 @@
 # conftest.py — project-level pytest configuration.
 #
 # Problem: custom_nodes/ComfyUI-Distributed/__init__.py uses relative imports
-# (from .distributed import ...) that fail when pytest tries to import it as a
+# (from .nodes.v3 import ...) that fail when pytest tries to import it as a
 # standalone module during Package.setup() for the root package node.
 #
 # Fix: patch Package.setup() to skip the root-package's __init__.py import.
@@ -1,51 +0,0 @@
-"""
-ComfyUI-Distributed: thin entry point.
-All implementation lives in workers/, nodes/, api/.
-"""
-import atexit
-import os
-
-import server
-
-from .utils.config import ensure_config_exists
-from .utils.logging import debug_log
-from .utils.network import cleanup_client_session
-from .workers import get_worker_manager
-from .workers.startup import delayed_auto_launch, register_async_signals, sync_cleanup
-from .upscale.job_store import ensure_tile_jobs_initialized
-from .nodes import (
-    NODE_CLASS_MAPPINGS,
-    NODE_DISPLAY_NAME_MAPPINGS,
-    ImageBatchDivider,
-    DistributedCollectorNode,
-    DistributedSeed,
-    DistributedModelName,
-    DistributedValue,
-    AudioBatchDivider,
-    DistributedEmptyImage,
-    AnyType,
-    ByPassTypeTuple,
-    any_type,
-)
-from . import api  # noqa: F401 - triggers all @routes.* registrations
-from .api.queue_orchestration import ensure_distributed_state
-
-ensure_config_exists()
-
-# Aiohttp session cleanup
-async def _cleanup_session():
-    await cleanup_client_session()
-
-
-atexit.register(lambda: None)  # placeholder; real cleanup in sync_cleanup
-
-# Initialize distributed job state on prompt_server
-prompt_server = server.PromptServer.instance
-ensure_distributed_state(prompt_server)
-ensure_tile_jobs_initialized()
-
-# Worker startup
-if not os.environ.get('COMFYUI_IS_WORKER'):
-    atexit.register(sync_cleanup)
-    delayed_auto_launch()
-    register_async_signals()
@@ -19,8 +19,8 @@ This document describes the **public HTTP API** added to ComfyUI-Distributed to
 - `POST /distributed/queue` — queues a workflow using the same distributed orchestration rules as the UI:
  - Detects distributed nodes in the prompt (`DistributedCollector`, `UltimateSDUpscaleDistributed`).
  - Resolves enabled/selected workers.
-  - Pings workers (`GET /prompt`) to include only reachable ones.
-  - Dispatches the workflow to workers (`POST /prompt`).
+  - Probes and dispatches workers through `/distributed/worker_ws` by default.
+  - If `settings.websocket_orchestration=false`, probes with `GET /prompt` and dispatches with `POST /prompt` instead.
  - Queues the master workflow in ComfyUI’s prompt queue.
  - If any `DistributedCollector` has `load_balance=true`, selects one least-busy participant for this run.

@@ -61,7 +61,8 @@ Queue a workflow for distributed execution.
 #### Fields

 - `prompt` (required unless `workflow.prompt` is present, object)
-  - The ComfyUI prompt/workflow graph, same shape as used by `POST /prompt`.
+  - A complete ComfyUI API-format prompt graph, using the same shape as `POST /prompt`.
+  - This is not the normal visual workflow export from the ComfyUI editor.
 - `workflow` (optional, object)
  - Workflow metadata that ComfyUI normally stores in `extra_pnginfo.workflow`.
  - If you don’t care about UI metadata, you can omit it.
@@ -123,10 +124,14 @@ $cfg.workers | Select-Object id,name,enabled,host,port,type | Format-Table -Auto

 ## Worker requirements (important)

-For a worker to participate, it must be reachable from the master:
+For a worker to participate, it must be reachable from the master. By default:
+
+- WebSocket probe and dispatch: `<worker-base>/distributed/worker_ws` must accept the connection.
+
+If `settings.websocket_orchestration=false`:

 - Health check: `GET <worker-base>/prompt` must return HTTP 200.
- Dispatch: `POST <worker-base>/prompt` must accept the workflow.
+- Dispatch: `POST <worker-base>/prompt` must accept the prompt.

 Also, for collector-based flows:

@@ -201,7 +206,7 @@ Proxy endpoint on master that fetches logs from a configured remote/cloud worker

 ## Examples

-### 1) Minimal `curl`
+### 1) Minimal `curl` request envelope

 ```bash
 curl -X POST "http://127.0.0.1:8188/distributed/queue" \
@@ -209,18 +214,23 @@ curl -X POST "http://127.0.0.1:8188/distributed/queue" \
  -d @payload.json
 ```

-Where `payload.json` contains at least:
+`payload.json` must contain a complete ComfyUI API-format prompt. The abbreviated envelope below illustrates the request shape but is not directly executable:

 ```json
 {
  "prompt": {
-    "1": {"class_type": "KSampler", "inputs": {} }
+    "<node_id>": {
+      "class_type": "<node class>",
+      "inputs": {"<required_input>": "<value or connection>"}
+    }
  },
  "enabled_worker_ids": [],
  "client_id": "external-client"
 }
 ```

+Export or construct a valid API-format prompt with all required node inputs and at least one output node before submitting it.
+
 ### 2) Python (`requests`)

 ```python
@@ -0,0 +1,38 @@
+# Compressed Result Transfer
+
+**Distributed Collector** has two optional widgets that control how workers send their images back to the master. This matters most when workers run in the cloud and you pay for data leaving it (egress).
+
+| `transfer_format` | Type | Notes |
+|---|---|---|
+| `legacy_png` (default) | lossless | Original behaviour: one JSON request per frame, uncompressed PNG in base64. Works with any master version. |
+| `png` | lossless | Compressed PNG, binary, several frames per request. Same tensors as `legacy_png`. |
+| `ffv1` | lossless | Whole batch as one FFV1 video. Same tensors as `legacy_png`; best lossless choice for frame sequences. |
+| `jpeg`, `webp` | lossy | Per-frame stills. Good for image batches. |
+| `h264`, `h265`, `av1` | lossy | Whole batch as one video. By far the smallest for video frame batches. |
+
+`transfer_quality` (1–100, default 90) applies to the lossy formats. JPEG/WebP use it directly; video codecs map it to CRF (90 → CRF 13 for h264/h265, CRF 16 for av1; 100 → CRF 0).
+
+Measured on a 121-frame 1280×720 batch (one worker's result):
+
+| Format | Sent | vs legacy | PSNR |
+|---|---|---|---|
+| `legacy_png` | 446 MB | 1× | lossless |
+| `png` | 163 MB | 2.7× | lossless |
+| `ffv1` | 128 MB | 3.5× | lossless |
+| `jpeg` q90 | 27 MB | 17× | 42.7 dB |
+| `webp` q90 | 13 MB | 33× | 40.6 dB |
+| `h264` q90 | 2.4 MB | 186× | 40.2 dB |
+| `h265` q90 | 1.0 MB | 434× | 40.1 dB |
+| `av1` q90 | 0.4 MB | 1031× | 40.5 dB |
+
+The test clip is a slow pan, which video codecs compress especially well; expect smaller (still large) gains on content with more motion.
+
+Notes:
+- Choose the format on the master; the value is sent to workers with the workflow.
+- The master must run this version to accept compressed results. A worker sending to an older master gets a 400 on its first request and automatically resends with `legacy_png`.
+- If a worker's PyAV build lacks the requested video encoder, it falls back to `h264` (lossy formats) or `png` (`ffv1`), and logs it.
+- Lossy formats only affect frames produced by workers; the master's own frames are never re-encoded.
+- Request size is bounded on the final encoded bytes. Frames are batched into requests of up to 32 MiB (`COMFYUI_DISTRIBUTED_TRANSFER_CHUNK_BYTES`); a single large frame may go alone in a request of up to 96 MiB (`COMFYUI_DISTRIBUTED_TRANSFER_MAX_REQUEST_BYTES`). Keep the latter below the master's `--max-upload-size` (default 100 MB) if you change either.
+- All chunks are encoded before anything is sent. If a single frame cannot fit within the request limit, the worker fails with an error and sends nothing; use a lossy format or raise both limits.
+- A rejection other than the older-master case above (for example the master's size limit, HTTP 413) is reported as an error rather than retried as `legacy_png`.
+- Each worker logs what it sent, e.g. `Sent 121 image(s) as h264 in 1 request(s): 2.40 MB (raw 334.49 MB, 139.4x smaller)`.
@@ -0,0 +1,53 @@
+# Native V3 node API
+
+The package registers one `ComfyExtension` through `comfy_entrypoint()` and
+imports the versioned `comfy_api.v0_0_2` API. Use a ComfyUI version that provides
+that API; there is no V1 registration fallback.
+
+## Compatibility
+
+- All eight node IDs, display names, categories, visible input order, defaults
+  and output order are retained. Existing execution algorithms remain in the
+  private collector, utilities and upscale modules.
+- The image/audio dividers explicitly declare ten typed outputs. Their existing
+  frontend extensions still show only the selected number of outputs. This
+  replaces the V1 `ByPassTypeTuple` indexing workaround without changing saved
+  IMAGE/AUDIO socket indices or the ten returned values.
+- Standard hidden context uses `cls.hidden`. Worker/orchestration metadata keeps
+  its existing prompt-input names and Python defaults via `accept_all_inputs`;
+  it does not become visible widgets.
+- The collector retains list-input handling. Upscale retains its always-changing
+  fingerprint and creates a private runtime helper for each V3 execution, so
+  mutable helper state is not attached to sanitized V3 class clones.
+- Routes, distributed state and the existing worker startup/shutdown hooks are
+  initialized by `runtime/bootstrap.py` during `ComfyExtension.on_load()`.
+  Worker mode still suppresses automatic worker launch. `distributed.py` is no
+  longer an entrypoint.
+
+## Verification
+
+Run ordinary unit tests from this repository:
+
+```bash
+python -m pytest tests -q -o addopts=
+```
+
+Opt into real-framework acceptance using a ComfyUI checkout and its interpreter:
+
+```bash
+COMFYUI_SOURCE_ROOT=/path/to/ComfyUI \
+  /path/to/ComfyUI/.venv/bin/python -m pytest tests -q -o addopts=
+```
+
+The acceptance subprocess uses CPU mode and the real ComfyUI loader, input
+parser, V3 class preparation, prompt validation and `PromptExecutor`. It compares
+all node schemas with the V1 fixture, checks all five bundled workflows' node
+IDs and socket/link contracts, exercises injected worker metadata, image/audio
+lists, collector aggregation and divider outputs, rejects invalid upscale enums,
+and decodes an actual preview PNG referenced by executor history.
+
+The upscale GPU/model boundary is mocked to check argument forwarding and
+per-execution helper isolation. Full checkpoint inference, browser canvas
+acceptance and multi-host HTTP transport are not exercised. No HTTP listener,
+workers or model downloads are started; preview files use a temporary scratch
+directory. The test does not install this branch into a live custom-node folder.
@@ -74,12 +74,14 @@ The master can either contribute GPU work or stay in **orchestrator-only** mode:

 > ComfyUI instances running on a cloud service like Runpod. 

+For faster result transfers and lower bandwidth usage, see [Compressed Result Transfer](compressed-result-transfer.md).
+
 ### Deploy Cloud Worker on Runpod

 📺 [Watch Tutorial](https://www.youtube.com/watch?v=wxKKWMQhYTk)

 **On Runpod:**
-> If using your own template, make sure you launch ComfyUI with the `--enable-cors-header` argument and you `git clone ComfyUI-Distributed` into custom_nodes. ⚠️ **Required!**
+> If using your own template, launch ComfyUI with `--listen --enable-cors-header` and clone `ComfyUI-Distributed` into `custom_nodes`. ⚠️ **Required!**

 1. Register a [Runpod](https://get.runpod.io/0bw29uf3ug0p) account.
 2. On Runpod, go to Storage > New Network Volume and create a volume that will store the models you need. Start with 40 GB, you can always add more later. Learn more [about Network Volumes](https://docs.runpod.io/pods/storage/create-network-volumes).
@@ -92,7 +94,7 @@ The master can either contribute GPU work or stay in **orchestrator-only** mode:
 	- SAGE_ATTENTION: optional optimisation (set to true/false)
 5. Deploy your pod.
 6. Connect to your pod using JupyterLabs. This gives us access to the pod's file system.
-7. Download models into /workspaces/ComfyUI/models/ (these will remain on your network drive even after you terminate the pod). Example commands below:
+7. Download models into `/workspace/ComfyUI/models/` (these will remain on your network drive even after you terminate the pod). Example commands below:
 ```
 # Download from CivitAI
 comfy model download --url https://civitai.com/api/download/models/1759168 --relative-path /workspace/ComfyUI/models/checkpoints --set-civitai-api-token $CIVITAI_API_TOKEN
@@ -1,31 +1 @@
-from .utilities import (
-    DistributedSeed,
-    DistributedModelName,
-    DistributedValue,
-    ImageBatchDivider,
-    AudioBatchDivider,
-    DistributedEmptyImage,
-    AnyType,
-    ByPassTypeTuple,
-    any_type,
-)
-from .collector import DistributedCollectorNode
-
-NODE_CLASS_MAPPINGS = {
-    "DistributedCollector": DistributedCollectorNode,
-    "DistributedSeed": DistributedSeed,
-    "DistributedModelName": DistributedModelName,
-    "DistributedValue": DistributedValue,
-    "ImageBatchDivider": ImageBatchDivider,
-    "AudioBatchDivider": AudioBatchDivider,
-    "DistributedEmptyImage": DistributedEmptyImage,
-}
-NODE_DISPLAY_NAME_MAPPINGS = {
-    "DistributedCollector": "Distributed Collector",
-    "DistributedSeed": "Distributed Seed",
-    "DistributedModelName": "Distributed Model Name",
-    "DistributedValue": "Distributed Value",
-    "ImageBatchDivider": "Image Batch Divider",
-    "AudioBatchDivider": "Audio Batch Divider",
-    "DistributedEmptyImage": "Distributed Empty Image",
-}
+"""Private execution helpers; public registration lives in nodes.v3."""
@@ -12,23 +12,29 @@ from comfy.utils import ProgressBar

 from ..utils.logging import debug_log, log
 from ..utils.config import get_worker_timeout_seconds, load_config, is_master_delegate_only
-from ..utils.constants import HEARTBEAT_INTERVAL
+from ..utils.constants import HEARTBEAT_INTERVAL, TRANSFER_MAX_CHUNK_BYTES, TRANSFER_MAX_REQUEST_BYTES
 from ..utils.image import tensor_to_pil, pil_to_tensor, ensure_contiguous
 from ..utils.network import build_worker_url, get_client_session, probe_worker
 from ..utils.audio_payload import encode_audio_payload
 from ..utils.async_helpers import run_async_in_server_loop
+from ..utils import transfer_codec

 prompt_server = _server.PromptServer.instance


+def _encode_all_chunks(frames, fmt, quality, max_chunk_bytes, max_frame_bytes):
+    """Materialize every transfer chunk (runs in an executor)."""
+    return list(transfer_codec.encode_chunks(frames, fmt, quality, max_chunk_bytes, max_frame_bytes))
+
+
 class DistributedCollectorNode:
+    INPUT_IS_LIST = True
    EMPTY_AUDIO = {"waveform": torch.zeros(1, 2, 1), "sample_rate": 44100}

    @classmethod
    def INPUT_TYPES(s):
        return {
            "required": {
-                "images": ("IMAGE",),
                "load_balance": (
                    "BOOLEAN",
                    {
@@ -37,7 +43,27 @@ class DistributedCollectorNode:
                    },
                ),
            },
-            "optional": { "audio": ("AUDIO",) },
+            "optional": {
+                "images": ("IMAGE",),
+                "audio": ("AUDIO",),
+                "transfer_format": (
+                    list(transfer_codec.TRANSFER_FORMATS),
+                    {
+                        "default": transfer_codec.DEFAULT_TRANSFER_FORMAT,
+                        "tooltip": transfer_codec.TRANSFER_FORMAT_TOOLTIP,
+                    },
+                ),
+                "transfer_quality": (
+                    "INT",
+                    {
+                        "default": transfer_codec.DEFAULT_TRANSFER_QUALITY,
+                        "min": 1,
+                        "max": 100,
+                        "step": 1,
+                        "tooltip": transfer_codec.TRANSFER_QUALITY_TOOLTIP,
+                    },
+                ),
+            },
            "hidden": {
                "multi_job_id": ("STRING", {"default": ""}),
                "is_worker": ("BOOLEAN", {"default": False}),
@@ -55,7 +81,76 @@ class DistributedCollectorNode:
    FUNCTION = "run"
    CATEGORY = "image"
    
-    def run(self, images, load_balance=False, audio=None, multi_job_id="", is_worker=False, master_url="", enabled_worker_ids="[]", worker_batch_size=1, worker_id="", pass_through=False, delegate_only=False):
+    @staticmethod
+    def _unwrap_list_input(value):
+        """Unwrap scalar inputs when ComfyUI passes them via INPUT_IS_LIST."""
+        if isinstance(value, (list, tuple)) and len(value) == 1:
+            return value[0]
+        return value
+
+    def _normalize_images_input(self, images):
+        """Collapse ComfyUI list IMAGE inputs into a normal batched IMAGE tensor."""
+        if isinstance(images, (list, tuple)):
+            if not images:
+                raise ValueError("Collector received an empty image list")
+            if not all(isinstance(image, torch.Tensor) for image in images):
+                raise TypeError("Collector expected IMAGE list items to be torch.Tensor instances")
+            if len(images) == 1:
+                return ensure_contiguous(images[0])
+            return ensure_contiguous(torch.cat([ensure_contiguous(image) for image in images], dim=0))
+        return ensure_contiguous(images)
+
+    def _normalize_audio_input(self, audio):
+        """Collapse ComfyUI list AUDIO inputs into a single AUDIO payload when present."""
+        if not isinstance(audio, (list, tuple)):
+            return audio
+
+        audio_items = [item for item in audio if item is not None]
+        if not audio_items:
+            return None
+        if len(audio_items) == 1:
+            return audio_items[0]
+
+        waveforms = []
+        sample_rate = 44100
+        for item in audio_items:
+            if not isinstance(item, dict):
+                raise TypeError("Collector expected AUDIO list items to be dictionaries")
+            waveform = item.get("waveform")
+            if waveform is None or waveform.numel() == 0:
+                continue
+            waveforms.append(waveform)
+            if sample_rate == 44100:
+                sample_rate = item.get("sample_rate", 44100)
+
+        if not waveforms:
+            return None
+        return {"waveform": torch.cat(waveforms, dim=-1), "sample_rate": sample_rate}
+
+    def run(self, images=None, load_balance=False, audio=None, multi_job_id="", is_worker=False, master_url="", enabled_worker_ids="[]", worker_batch_size=1, worker_id="", pass_through=False, delegate_only=False, transfer_format=transfer_codec.DEFAULT_TRANSFER_FORMAT, transfer_quality=transfer_codec.DEFAULT_TRANSFER_QUALITY):
+        if images is not None:
+            images = self._normalize_images_input(images)
+        audio = self._normalize_audio_input(audio)
+        load_balance = self._unwrap_list_input(load_balance)
+        multi_job_id = self._unwrap_list_input(multi_job_id)
+        is_worker = self._unwrap_list_input(is_worker)
+        master_url = self._unwrap_list_input(master_url)
+        enabled_worker_ids = self._unwrap_list_input(enabled_worker_ids)
+        worker_batch_size = self._unwrap_list_input(worker_batch_size)
+        worker_id = self._unwrap_list_input(worker_id)
+        pass_through = self._unwrap_list_input(pass_through)
+        delegate_only = self._unwrap_list_input(delegate_only)
+        transfer_format = self._unwrap_list_input(transfer_format)
+        transfer_quality = self._unwrap_list_input(transfer_quality)
+
+        remote_only_master = (
+            bool(multi_job_id)
+            and not is_worker
+            and (delegate_only or is_master_delegate_only())
+        )
+        if images is None and audio is None and not remote_only_master:
+            raise ValueError("DistributedCollector requires at least one image or audio input")
+
        # Create empty audio if not provided
        empty_audio = {"waveform": torch.zeros(1, 2, 1), "sample_rate": 44100}

@@ -77,46 +172,209 @@ class DistributedCollectorNode:
                worker_batch_size,
                worker_id,
                delegate_only,
+                transfer_format,
+                transfer_quality,
            )
        )
        return result

-    async def send_batch_to_master(self, image_batch, audio, multi_job_id, master_url, worker_id):
-        """Send image batch to master via canonical JSON envelopes."""
-        batch_size = image_batch.shape[0]
-        if batch_size == 0:
-            return
+    async def send_batch_to_master(
+        self,
+        image_batch,
+        audio,
+        multi_job_id,
+        master_url,
+        worker_id,
+        transfer_format=transfer_codec.DEFAULT_TRANSFER_FORMAT,
+        transfer_quality=transfer_codec.DEFAULT_TRANSFER_QUALITY,
+    ):
+        """Send an image batch, optionally with audio, or an audio-only completion."""
+        batch_size = 0 if image_batch is None else image_batch.shape[0]
+        fmt = self._resolve_transfer_format(transfer_format) if batch_size else transfer_codec.LEGACY_FORMAT
+        if fmt != transfer_codec.LEGACY_FORMAT:
+            sent = await self._send_compressed_batch(
+                image_batch, audio, multi_job_id, master_url, worker_id, fmt, transfer_quality
+            )
+            if sent:
+                return
+            log(
+                "Worker - Master did not accept compressed transfer "
+                "(older ComfyUI-Distributed on the master?). Falling back to legacy_png."
+            )
+        await self._send_legacy_batch(image_batch, audio, multi_job_id, master_url, worker_id)

+    @staticmethod
+    def _resolve_transfer_format(transfer_format):
+        try:
+            fmt = transfer_codec.normalize_format(transfer_format)
+        except transfer_codec.TransferCodecError as exc:
+            log(f"Worker - {exc}; using legacy_png.")
+            return transfer_codec.LEGACY_FORMAT
+        if fmt not in transfer_codec.VIDEO_FORMATS or transfer_codec.video_codec_available(fmt):
+            return fmt
+        fallback = "h264" if fmt != "ffv1" and transfer_codec.video_codec_available("h264") else "png"
+        log(f"Worker - Encoder for '{fmt}' is not available in this PyAV build; using '{fallback}'.")
+        return fallback
+
+    @staticmethod
+    def _build_multipart(envelope, parts):
+        form = aiohttp.FormData()
+        form.add_field("envelope", json.dumps(envelope), content_type="application/json")
+        for i, data in enumerate(parts):
+            form.add_field("media", data, filename=f"{i}.bin", content_type="application/octet-stream")
+        return form
+
+    # Room left in each request for the multipart envelope (ids, frame
+    # metadata, part headers). Audio is budgeted separately.
+    TRANSFER_ENVELOPE_RESERVE_BYTES = 256 * 1024
+    # Body of a 400 from a master without compressed-transfer support: it
+    # tries request.json() on the multipart body and fails.
+    _OLD_MASTER_REJECTION = "Invalid JSON payload"
+
+    async def _send_compressed_batch(self, image_batch, audio, multi_job_id, master_url, worker_id, fmt, quality):
+        """Send the batch as compressed multipart chunks.
+
+        All chunks are encoded before anything is sent, so a frame that cannot
+        fit in one request fails the transfer without delivering a partial
+        batch. Every request stays within TRANSFER_MAX_REQUEST_BYTES.
+
+        Returns False (without having delivered anything) when the master
+        rejects the first chunk because it predates compressed transfer, so
+        the caller can retry with legacy_png. Any other rejection raises.
+        """
        encoded_audio = encode_audio_payload(audio)
-
        session = await get_client_session()
        url = f"{master_url}/distributed/job_complete"
-        for batch_idx in range(batch_size):
-            img = tensor_to_pil(image_batch[batch_idx:batch_idx+1], 0)
-            byte_io = io.BytesIO()
-            img.save(byte_io, format='PNG', compress_level=0)
-            encoded_image = base64.b64encode(byte_io.getvalue()).decode('utf-8')
-            payload = {
+        loop = asyncio.get_running_loop()
+
+        frames = await loop.run_in_executor(None, transfer_codec.tensor_batch_to_uint8, image_batch)
+        raw_bytes = int(frames.nbytes)
+        total = int(frames.shape[0])
+        media_limit = max(1, TRANSFER_MAX_REQUEST_BYTES - self.TRANSFER_ENVELOPE_RESERVE_BYTES)
+        started = time.time()
+        # Encoding is CPU-bound (seconds for video); keep the server loop responsive.
+        chunks = await loop.run_in_executor(
+            None, _encode_all_chunks, frames, fmt, quality, min(TRANSFER_MAX_CHUNK_BYTES, media_limit), media_limit,
+        )
+        del frames
+
+        # Attach audio to the final chunk only if the request stays in bounds;
+        # otherwise finish with a separate audio-only completion.
+        audio_bytes = len(json.dumps(encoded_audio)) if encoded_audio is not None else 0
+        last_media = sum(len(p) for p in chunks[-1]["parts"])
+        audio_inline = encoded_audio is not None and last_media + audio_bytes <= media_limit
+        audio_separate = encoded_audio is not None and not audio_inline
+
+        sent_bytes = 0
+        for index, chunk in enumerate(chunks):
+            parts = chunk.pop("parts")
+            is_final_chunk = index == len(chunks) - 1
+            envelope = {
                "job_id": str(multi_job_id),
                "worker_id": str(worker_id),
-                "batch_idx": int(batch_idx),
-                "image": f"data:image/png;base64,{encoded_image}",
-                "is_last": bool(batch_idx == batch_size - 1),
+                "is_last": bool(is_final_chunk and not audio_separate),
+                **chunk,
            }
-            if payload["is_last"] and encoded_audio is not None:
-                payload["audio"] = encoded_audio
-
+            if is_final_chunk and audio_inline:
+                envelope["audio"] = encoded_audio
+            chunk_bytes = sum(len(p) for p in parts)
+            timeout_seconds = min(600, 60 + chunk_bytes // (256 * 1024))
            try:
                async with session.post(
                    url,
-                    json=payload,
-                    timeout=aiohttp.ClientTimeout(total=60),
+                    data=self._build_multipart(envelope, parts),
+                    timeout=aiohttp.ClientTimeout(total=timeout_seconds),
                ) as response:
-                    response.raise_for_status()
+                    if response.status >= 400:
+                        body = await response.text()
+                        if index == 0 and response.status == 400 and self._OLD_MASTER_REJECTION in body:
+                            debug_log(f"Worker - Master rejected compressed chunk: {body[:300]}")
+                            return False
+                        raise RuntimeError(
+                            f"Master rejected {fmt} chunk {index + 1}/{len(chunks)} "
+                            f"({chunk_bytes} bytes) with HTTP {response.status}: {body[:300]}. "
+                            "If this is a size limit, make COMFYUI_DISTRIBUTED_TRANSFER_MAX_REQUEST_BYTES "
+                            "on the worker smaller than the master's --max-upload-size."
+                        )
            except Exception as e:
-                log(f"Worker - Failed to send canonical image envelope to master: {e}")
+                log(f"Worker - Failed to send {fmt} chunk to master: {e}")
                debug_log(f"Worker - Full error details: URL={url}")
-                raise  # Re-raise to handle at caller level
+                raise
+            sent_bytes += chunk_bytes
+
+        requests = len(chunks)
+        if audio_separate:
+            await self._post_json_completion(session, url, {
+                "job_id": str(multi_job_id),
+                "worker_id": str(worker_id),
+                "batch_idx": 0,
+                "audio": encoded_audio,
+                "is_last": True,
+            })
+            requests += 1
+
+        log(
+            f"Worker - Sent {total} image(s) as {fmt} in {requests} request(s): "
+            f"{sent_bytes / 1e6:.2f} MB (raw {raw_bytes / 1e6:.2f} MB, "
+            f"{transfer_codec.describe_ratio(sent_bytes, raw_bytes)} smaller) in {time.time() - started:.1f}s"
+        )
+        return True
+
+    @staticmethod
+    async def _post_json_completion(session, url, payload):
+        timeout_seconds = 60 if "image" in payload else 600
+        try:
+            async with session.post(
+                url,
+                json=payload,
+                timeout=aiohttp.ClientTimeout(total=timeout_seconds),
+            ) as response:
+                response.raise_for_status()
+        except Exception as e:
+            media_type = "image/audio" if "image" in payload else "audio-only"
+            log(f"Worker - Failed to send canonical {media_type} envelope to master: {e}")
+            debug_log(f"Worker - Full error details: URL={url}")
+            raise
+
+    async def _send_legacy_batch(self, image_batch, audio, multi_job_id, master_url, worker_id):
+        """Original transfer: one JSON request per frame with a base64 PNG."""
+        encoded_audio = encode_audio_payload(audio)
+        session = await get_client_session()
+        url = f"{master_url}/distributed/job_complete"
+
+        payloads = []
+        batch_size = 0 if image_batch is None else image_batch.shape[0]
+        if batch_size == 0:
+            if encoded_audio is None:
+                raise ValueError("Worker completion requires image or audio data")
+            payloads.append(
+                {
+                    "job_id": str(multi_job_id),
+                    "worker_id": str(worker_id),
+                    "batch_idx": 0,
+                    "audio": encoded_audio,
+                    "is_last": True,
+                }
+            )
+        else:
+            for batch_idx in range(batch_size):
+                img = tensor_to_pil(image_batch[batch_idx:batch_idx+1], 0)
+                byte_io = io.BytesIO()
+                img.save(byte_io, format='PNG', compress_level=0)
+                encoded_image = base64.b64encode(byte_io.getvalue()).decode('utf-8')
+                payload = {
+                    "job_id": str(multi_job_id),
+                    "worker_id": str(worker_id),
+                    "batch_idx": int(batch_idx),
+                    "image": f"data:image/png;base64,{encoded_image}",
+                    "is_last": bool(batch_idx == batch_size - 1),
+                }
+                if payload["is_last"] and encoded_audio is not None:
+                    payload["audio"] = encoded_audio
+                payloads.append(payload)
+
+        for payload in payloads:
+            await self._post_json_completion(session, url, payload)

    def _combine_audio(self, master_audio, worker_audio, empty_audio, worker_order=None):
        """Combine audio from master and workers into a single audio output.
@@ -198,8 +456,8 @@ class DistributedCollectorNode:
        images_on_cpu,
        delegate_mode: bool,
        fallback_images,
-    ) -> torch.Tensor:
-        """Assemble final tensor: master first, then workers in enabled order."""
+    ):
+        """Assemble final tensor, or return None when the job contains only audio."""
        ordered_tensors = []
        if not delegate_mode and images_on_cpu is not None:
            for i in range(master_batch_size):
@@ -230,16 +488,18 @@ class DistributedCollectorNode:

        if cpu_tensors:
            return ensure_contiguous(torch.cat(cpu_tensors, dim=0))
-        elif fallback_images is not None:
+        if fallback_images is not None:
            return ensure_contiguous(fallback_images)
-        else:
-            raise ValueError("No image data collected from master or workers")
+        return None

-    async def execute(self, images, audio, load_balance=False, multi_job_id="", is_worker=False, master_url="", enabled_worker_ids="[]", worker_batch_size=1, worker_id="", delegate_only=False):
+    async def execute(self, images, audio, load_balance=False, multi_job_id="", is_worker=False, master_url="", enabled_worker_ids="[]", worker_batch_size=1, worker_id="", delegate_only=False, transfer_format=transfer_codec.DEFAULT_TRANSFER_FORMAT, transfer_quality=transfer_codec.DEFAULT_TRANSFER_QUALITY):
        if is_worker:
            # Worker mode: send images and audio to master in a single batch
-            debug_log(f"Worker - Job {multi_job_id} complete. Sending {images.shape[0]} image(s) to master")
-            await self.send_batch_to_master(images, audio, multi_job_id, master_url, worker_id)
+            image_count = 0 if images is None else images.shape[0]
+            debug_log(f"Worker - Job {multi_job_id} complete. Sending {image_count} image(s) to master")
+            await self.send_batch_to_master(
+                images, audio, multi_job_id, master_url, worker_id, transfer_format, transfer_quality
+            )
            return (images, audio if audio is not None else self.EMPTY_AUDIO)
        else:
            delegate_mode = delegate_only or is_master_delegate_only()
@@ -273,14 +533,15 @@ class DistributedCollectorNode:
                master_audio = None
                debug_log(f"Master - Job {multi_job_id}: Delegate-only mode enabled, collecting exclusively from {num_workers} workers")
            else:
-                images_on_cpu = images.cpu()
-                master_batch_size = images.shape[0]
+                if images is None:
+                    images_on_cpu = None
+                    master_batch_size = 0
+                else:
+                    images_on_cpu = ensure_contiguous(images.cpu())
+                    master_batch_size = images.shape[0]
                master_audio = audio  # Keep master's audio for later
                debug_log(f"Master - Job {multi_job_id}: Master has {master_batch_size} images, collecting from {num_workers} workers...")

-                # Ensure master images are contiguous
-                images_on_cpu = ensure_contiguous(images_on_cpu)
-

            # Initialize storage for collected images and audio
            worker_images = {}  # Dict to store images by worker_id and index
@@ -452,18 +713,19 @@ class DistributedCollectorNode:
                if multi_job_id in prompt_server.distributed_pending_jobs:
                    del prompt_server.distributed_pending_jobs[multi_job_id]

+            combined_audio = self._combine_audio(master_audio, worker_audio, self.EMPTY_AUDIO, enabled_workers)
            try:
                combined = self._reorder_and_combine_tensors(
                    worker_images, enabled_workers, master_batch_size, images_on_cpu, delegate_mode, images
                )
-                debug_log(f"Master - Job {multi_job_id} complete. Combined {combined.shape[0]} images total "
-                          f"(master: {master_batch_size}, workers: {combined.shape[0] - master_batch_size})")
-
-                # Combine audio from master and workers
-                combined_audio = self._combine_audio(master_audio, worker_audio, self.EMPTY_AUDIO, enabled_workers)
+                if combined is None:
+                    debug_log(f"Master - Job {multi_job_id} complete with audio only")
+                else:
+                    debug_log(f"Master - Job {multi_job_id} complete. Combined {combined.shape[0]} images total "
+                              f"(master: {master_batch_size}, workers: {combined.shape[0] - master_batch_size})")

                return (combined, combined_audio)
            except Exception as e:
                log(f"Master - Error combining images: {e}")
-                # Return just the master images as fallback
-                return (images, audio if audio is not None else self.EMPTY_AUDIO)
+                # Preserve collected audio even when image assembly fails.
+                return (images, combined_audio)
@@ -56,22 +56,22 @@ class UltimateSDUpscaleDistributed(
    """
    Distributed version of Ultimate SD Upscale (No Upscale).
    
-    Supports three processing modes:
+    Supports two currently selected processing modes:
    1. Single GPU: No workers available, process everything locally
-    2. Static Mode: Small batches, distributes tiles across workers (flattened)
-    3. Dynamic Mode: Large batches, assigns whole images to workers dynamically
+    2. Distributed tile queue: Workers pull tiles from a shared queue
    
    Features:
-    - Multi-mode batch handling for efficient video/image upscaling
+    - Tile-based batch handling for video/image upscaling
    - Tiled VAE support for memory efficiency
-    - Dynamic load balancing for large batches
+    - Shared work queue so faster workers can process more tiles
    - Backward compatible with single-image workflows
    
    Environment Variables:
    - COMFYUI_MAX_BATCH: Chunk size for tile sending (default 20)
    - COMFYUI_MAX_PAYLOAD_SIZE: Max API payload bytes (default 50MB)
    
-    Threshold: dynamic_threshold input controls mode switch (default 8)
+    The hidden dynamic_threshold input is retained for workflow compatibility but
+    does not affect the current mode-selection policy.
    """

    def __init__(self):
@@ -268,12 +268,3 @@ class UltimateSDUpscaleDistributed(

 # Ensure initialization before registering routes
 ensure_tile_jobs_initialized()
-
-# Node registration
-NODE_CLASS_MAPPINGS = {
-    "UltimateSDUpscaleDistributed": UltimateSDUpscaleDistributed,
-}
-
-NODE_DISPLAY_NAME_MAPPINGS = {
-    "UltimateSDUpscaleDistributed": "Ultimate SD Upscale Distributed (No Upscale)",
-}
@@ -269,7 +269,7 @@ class ImageBatchDivider:


 class AudioBatchDivider:
-    """Divides an audio waveform into multiple parts along the time/samples dimension."""
+    """Divides an audio waveform into sequential segments along the time dimension."""

    @classmethod
    def INPUT_TYPES(s):
@@ -282,7 +282,7 @@ class AudioBatchDivider:
                    "max": 10,
                    "step": 1,
                    "display": "number",
-                    "tooltip": "Number of parts to divide the audio into"
+                    "tooltip": "Number of sequential time segments to create"
                }),
            }
        }
@@ -0,0 +1,191 @@
+"""Native V3 schemas with the existing execution algorithms kept intact.
+
+Runtime objects are private, per-execution helpers, not registered V1 nodes.
+This avoids sharing mutable instance state through V3's sanitized class clones.
+"""
+import comfy.samplers
+from comfy_api.v0_0_2 import io
+
+from . import utilities as _utilities
+from .collector import DistributedCollectorNode as _CollectorRuntime
+from ..utils import transfer_codec as _transfer_codec
+from .distributed_upscale import UltimateSDUpscaleDistributed as _UpscaleRuntime
+
+
+class DistributedSeed(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='DistributedSeed', display_name='Distributed Seed', category='utils',
+            inputs=[io.Int.Input('seed', default=1125899906842, min=0,
+                                 max=1125899906842624, force_input=False)],
+            outputs=[io.Int.Output(display_name='seed')],
+            accept_all_inputs=True,
+        )
+
+    @classmethod
+    def execute(cls, seed, is_worker=False, worker_id=''):
+        return io.NodeOutput(*_utilities.DistributedSeed().distribute(seed, is_worker, worker_id))
+
+
+class DistributedValue(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='DistributedValue', display_name='Distributed Value', category='utils',
+            inputs=[io.String.Input('default_value', default=''),
+                    io.String.Input('worker_values', default='{}')],
+            outputs=[io.AnyType.Output(display_name='value')],
+            accept_all_inputs=True,
+        )
+
+    @classmethod
+    def execute(cls, default_value, worker_values='{}', is_worker=False, worker_id=''):
+        return io.NodeOutput(*_utilities.DistributedValue().distribute(
+            default_value, worker_values, is_worker, worker_id))
+
+
+class DistributedModelName(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='DistributedModelName', display_name='Distributed Model Name', category='utils',
+            inputs=[io.String.Input('text', default='')],
+            outputs=[io.AnyType.Output(display_name='output')],
+            hidden=[io.Hidden.unique_id, io.Hidden.extra_pnginfo], is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, text):
+        result = _utilities.DistributedModelName().log_input(
+            text, unique_id=cls.hidden.unique_id, extra_pnginfo=cls.hidden.extra_pnginfo)
+        return io.NodeOutput(*result['result'], ui=result['ui'])
+
+
+class ImageBatchDivider(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='ImageBatchDivider', display_name='Image Batch Divider', category='image',
+            inputs=[io.Image.Input('images'),
+                    io.Int.Input('divide_by', default=2, min=1, max=10, step=1,
+                                 display_mode=io.NumberDisplay.number,
+                                 tooltip='Number of parts to divide the batch into')],
+            # The existing frontend still displays only divide_by sockets.
+            outputs=[io.Image.Output(display_name=f'batch_{index + 1}') for index in range(10)],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, images, divide_by):
+        return io.NodeOutput(*_utilities.ImageBatchDivider().divide_batch(images, divide_by))
+
+
+class AudioBatchDivider(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='AudioBatchDivider', display_name='Audio Segment Divider', category='audio',
+            inputs=[io.Audio.Input('audio'),
+                    io.Int.Input('divide_by', default=2, min=1, max=10, step=1,
+                                 display_mode=io.NumberDisplay.number,
+                                 tooltip='Number of sequential time segments to create')],
+            outputs=[io.Audio.Output(display_name=f'audio_{index + 1}') for index in range(10)],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, audio, divide_by):
+        return io.NodeOutput(*_utilities.AudioBatchDivider().divide_audio(audio, divide_by))
+
+
+class DistributedEmptyImage(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='DistributedEmptyImage', display_name='Distributed Empty Image', category='image',
+            inputs=[io.Int.Input('height', default=64, min=1, max=4096, step=1),
+                    io.Int.Input('width', default=64, min=1, max=4096, step=1),
+                    io.Int.Input('channels', default=3, min=1, max=4, step=1)],
+            outputs=[io.Image.Output()],
+        )
+
+    @classmethod
+    def execute(cls, height, width, channels):
+        return io.NodeOutput(*_utilities.DistributedEmptyImage().create(height, width, channels))
+
+
+class DistributedCollector(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='DistributedCollector', display_name='Distributed Collector', category='image',
+            inputs=[io.Boolean.Input('load_balance', default=False,
+                                     tooltip='Run this workflow on one least-busy participant (master included when participating).'),
+                    io.Image.Input('images', optional=True), io.Audio.Input('audio', optional=True),
+                    io.Combo.Input('transfer_format', options=list(_transfer_codec.TRANSFER_FORMATS),
+                                   default=_transfer_codec.DEFAULT_TRANSFER_FORMAT, optional=True,
+                                   tooltip=_transfer_codec.TRANSFER_FORMAT_TOOLTIP),
+                    io.Int.Input('transfer_quality', default=_transfer_codec.DEFAULT_TRANSFER_QUALITY,
+                                 min=1, max=100, step=1, optional=True,
+                                 tooltip=_transfer_codec.TRANSFER_QUALITY_TOOLTIP)],
+            outputs=[io.Image.Output(display_name='images'), io.Audio.Output(display_name='audio')],
+            is_input_list=True, accept_all_inputs=True,
+        )
+
+    @classmethod
+    def execute(cls, images=None, load_balance=False, audio=None, multi_job_id='',
+                is_worker=False, master_url='', enabled_worker_ids='[]', worker_batch_size=1,
+                worker_id='', pass_through=False, delegate_only=False,
+                transfer_format=_transfer_codec.DEFAULT_TRANSFER_FORMAT,
+                transfer_quality=_transfer_codec.DEFAULT_TRANSFER_QUALITY):
+        return io.NodeOutput(*_CollectorRuntime().run(
+            images=images, load_balance=load_balance, audio=audio, multi_job_id=multi_job_id,
+            is_worker=is_worker, master_url=master_url, enabled_worker_ids=enabled_worker_ids,
+            worker_batch_size=worker_batch_size, worker_id=worker_id,
+            pass_through=pass_through, delegate_only=delegate_only,
+            transfer_format=transfer_format, transfer_quality=transfer_quality))
+
+
+class UltimateSDUpscaleDistributed(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id='UltimateSDUpscaleDistributed',
+            display_name='Ultimate SD Upscale Distributed (No Upscale)', category='image/upscaling',
+            inputs=[
+                io.Image.Input('upscaled_image'), io.Model.Input('model'),
+                io.Conditioning.Input('positive'), io.Conditioning.Input('negative'), io.Vae.Input('vae'),
+                io.Int.Input('seed', default=0, min=0, max=0xffffffffffffffff),
+                io.Int.Input('steps', default=20, min=1, max=10000),
+                io.Float.Input('cfg', default=8.0, min=0.0, max=100.0),
+                io.Combo.Input('sampler_name', options=comfy.samplers.KSampler.SAMPLERS),
+                io.Combo.Input('scheduler', options=comfy.samplers.KSampler.SCHEDULERS),
+                io.Float.Input('denoise', default=0.5, min=0.0, max=1.0, step=0.01),
+                io.Int.Input('tile_width', default=512, min=64, max=2048, step=8),
+                io.Int.Input('tile_height', default=512, min=64, max=2048, step=8),
+                io.Int.Input('padding', default=32, min=0, max=256, step=8),
+                io.Int.Input('mask_blur', default=8, min=0, max=256),
+                io.Boolean.Input('force_uniform_tiles', default=True),
+                io.Boolean.Input('tiled_decode', default=False),
+            ], outputs=[io.Image.Output()], accept_all_inputs=True,
+        )
+
+    @classmethod
+    def fingerprint_inputs(cls, **kwargs):
+        return _UpscaleRuntime.IS_CHANGED(**kwargs)
+
+    @classmethod
+    def execute(cls, upscaled_image, model, positive, negative, vae, seed, steps, cfg,
+                sampler_name, scheduler, denoise, tile_width, tile_height, padding,
+                mask_blur, force_uniform_tiles, tiled_decode, multi_job_id='', is_worker=False,
+                master_url='', enabled_worker_ids='[]', worker_id='', tile_indices='', dynamic_threshold=8):
+        return io.NodeOutput(*_UpscaleRuntime().run(
+            upscaled_image, model, positive, negative, vae, seed, steps, cfg,
+            sampler_name, scheduler, denoise, tile_width, tile_height, padding,
+            mask_blur, force_uniform_tiles, tiled_decode, multi_job_id, is_worker,
+            master_url, enabled_worker_ids, worker_id, tile_indices, dynamic_threshold))
+
+
+NODES = [DistributedCollector, DistributedSeed, DistributedModelName, DistributedValue,
+         ImageBatchDivider, AudioBatchDivider, DistributedEmptyImage, UltimateSDUpscaleDistributed]
@@ -1,7 +1,7 @@
 [project]
 name = "ComfyUI-Distributed"
 description = "ComfyUI extension that enables multi-GPU processing locally, remotely and in the cloud"
-version = "1.3.1"
+version = "1.5.0"
 license = {file = "LICENSE"}
 dependencies  = []

@@ -0,0 +1 @@
+"""Internal extension lifecycle support (not a node provider)."""
@@ -0,0 +1,35 @@
+"""Initialize routes, distributed state and the existing worker lifecycle."""
+import atexit
+import os
+
+import server
+
+from ..utils.config import CONFIG_FILE, ensure_config_exists
+from ..utils.logging import debug_log
+from ..workers.startup import delayed_auto_launch, register_async_signals, sync_cleanup
+from ..upscale.job_store import ensure_tile_jobs_initialized
+
+_initialized = False
+
+
+def initialize():
+    """Called by ComfyExtension.on_load; initialize once per loaded package."""
+    global _initialized
+    if _initialized:
+        return
+
+    ensure_config_exists()
+    from .. import api  # noqa: F401 - registers the existing @routes.* handlers
+    from ..api.queue_orchestration import ensure_distributed_state
+
+    ensure_distributed_state(server.PromptServer.instance)
+    ensure_tile_jobs_initialized()
+
+    if not os.environ.get('COMFYUI_IS_WORKER'):
+        atexit.register(sync_cleanup)
+        delayed_auto_launch()
+        register_async_signals()
+
+    _initialized = True
+    debug_log('Loaded Distributed nodes.')
+    debug_log(f'Config file: {CONFIG_FILE}')
@@ -4,6 +4,8 @@ import types
 import unittest
 import asyncio
 import base64
+import io
+import json
 from dataclasses import dataclass
 from pathlib import Path
 from unittest.mock import AsyncMock, patch
@@ -26,6 +28,17 @@ class _FakeRequest:
        return self._payload


+def _register_real_transfer_codec(package_name, utils_pkg):
+    """Load the real utils/transfer_codec.py into the synthetic test package."""
+    codec_path = Path(__file__).resolve().parents[2] / "utils" / "transfer_codec.py"
+    codec_spec = importlib.util.spec_from_file_location(f"{package_name}.utils.transfer_codec", codec_path)
+    codec_module = importlib.util.module_from_spec(codec_spec)
+    sys.modules[f"{package_name}.utils.transfer_codec"] = codec_module
+    codec_spec.loader.exec_module(codec_module)
+    utils_pkg.transfer_codec = codec_module
+    return codec_module
+
+
 def _load_job_routes_module():
    module_path = Path(__file__).resolve().parents[2] / "api" / "job_routes.py"
    package_name = "dist_api_queue_testpkg"
@@ -46,6 +59,7 @@ def _load_job_routes_module():
    utils_pkg = types.ModuleType(f"{package_name}.utils")
    utils_pkg.__path__ = []
    sys.modules[f"{package_name}.utils"] = utils_pkg
+    _register_real_transfer_codec(package_name, utils_pkg)

    # aiohttp.web stub
    created_aiohttp_stub = False
@@ -162,7 +176,7 @@ def _load_job_routes_module():
    sys.modules[f"{package_name}.utils.async_helpers"] = async_helpers_module

    queue_orchestration_module = types.ModuleType(f"{package_name}.api.queue_orchestration")
-    queue_orchestration_module.orchestrate_distributed_execution = AsyncMock(return_value=("prompt_dist", 1))
+    queue_orchestration_module.orchestrate_distributed_execution = AsyncMock(return_value=("prompt_dist", 7, 1, {}))
    sys.modules[f"{package_name}.api.queue_orchestration"] = queue_orchestration_module

    @dataclass(frozen=True)
@@ -221,7 +235,7 @@ job_routes = _load_job_routes_module()


 class DistributedQueueEndpointTests(unittest.IsolatedAsyncioTestCase):
-    async def test_distributed_queue_happy_path_returns_prompt_id(self):
+    async def test_distributed_queue_happy_path_returns_prompt_metadata(self):
        request = _FakeRequest(
            {
                "prompt": {"1": {"class_type": "Node"}},
@@ -233,12 +247,14 @@ class DistributedQueueEndpointTests(unittest.IsolatedAsyncioTestCase):
        with patch.object(
            job_routes,
            "orchestrate_distributed_execution",
-            new=AsyncMock(return_value=("prompt_123", 2)),
+            new=AsyncMock(return_value=("prompt_123", 42, 2, {})),
        ):
            response = await job_routes.distributed_queue_endpoint(request)

        self.assertEqual(response.status, 200)
        self.assertEqual(response.payload.get("prompt_id"), "prompt_123")
+        self.assertEqual(response.payload.get("number"), 42)
+        self.assertEqual(response.payload.get("node_errors"), {})
        self.assertTrue(response.payload.get("auto_prepare_supported"))

    async def test_distributed_queue_missing_prompt_returns_400(self):
@@ -300,6 +316,77 @@ class JobCompleteAudioPayloadTests(unittest.IsolatedAsyncioTestCase):
        self.assertEqual(queued["audio"]["sample_rate"], 44100)
        self.assertEqual(tuple(queued["audio"]["waveform"].shape), (1, 2, 4))

+    async def test_job_complete_accepts_audio_without_image(self):
+        queue = asyncio.Queue()
+        job_routes.prompt_server.distributed_jobs_lock = asyncio.Lock()
+        job_routes.prompt_server.distributed_pending_jobs = {"audio-only-job": queue}
+        request = _FakeRequest(
+            {
+                "job_id": "audio-only-job",
+                "worker_id": "worker-1",
+                "batch_idx": 0,
+                "audio": self._encoded_audio_payload(),
+                "is_last": True,
+            }
+        )
+
+        with patch.object(job_routes, "_decode_canonical_png_tensor") as decode_image:
+            response = await job_routes.job_complete_endpoint(request)
+
+        self.assertEqual(response.status, 200)
+        decode_image.assert_not_called()
+        queued = await queue.get()
+        self.assertIsNone(queued["tensor"])
+        self.assertEqual(queued["audio"]["sample_rate"], 44100)
+
+    async def test_job_complete_rejects_payload_without_image_or_audio(self):
+        request = _FakeRequest(
+            {
+                "job_id": "job-1",
+                "worker_id": "worker-1",
+                "batch_idx": 0,
+                "is_last": True,
+            }
+        )
+
+        response = await job_routes.job_complete_endpoint(request)
+
+        self.assertEqual(response.status, 400)
+        self.assertIn("image or audio", response.payload.get("message", "").lower())
+
+    async def test_job_complete_rejects_invalid_image_even_when_audio_is_present(self):
+        request = _FakeRequest(
+            {
+                "job_id": "job-1",
+                "worker_id": "worker-1",
+                "batch_idx": 0,
+                "image": 123,
+                "audio": self._encoded_audio_payload(),
+                "is_last": True,
+            }
+        )
+
+        response = await job_routes.job_complete_endpoint(request)
+
+        self.assertEqual(response.status, 400)
+        self.assertIn("image", response.payload.get("message", "").lower())
+
+    async def test_job_complete_returns_400_for_malformed_audio(self):
+        request = _FakeRequest(
+            {
+                "job_id": "job-1",
+                "worker_id": "worker-1",
+                "batch_idx": 0,
+                "audio": {"data": "AAAA", "shape": [1, 2], "dtype": "float32"},
+                "is_last": True,
+            }
+        )
+
+        response = await job_routes.job_complete_endpoint(request)
+
+        self.assertEqual(response.status, 400)
+        self.assertIn("audio.shape", response.payload.get("message", "").lower())
+
    def test_decode_audio_payload_rejects_bad_shape(self):
        bad = {
            "sample_rate": 44100,
@@ -321,5 +408,144 @@ class JobCompleteAudioPayloadTests(unittest.IsolatedAsyncioTestCase):
            job_routes._decode_audio_payload(payload)


+class _FakeFileField:
+    def __init__(self, data):
+        self.file = io.BytesIO(data)
+
+
+class _FakeMultipartRequest:
+    content_type = "multipart/form-data"
+
+    def __init__(self, envelope, parts):
+        from multidict import MultiDict
+
+        fields = [("envelope", envelope if isinstance(envelope, str) else json.dumps(envelope))]
+        fields += [("media", _FakeFileField(part)) for part in parts]
+        self._form = MultiDict(fields)
+
+    async def post(self):
+        return self._form
+
+    async def json(self):
+        raise ValueError("not JSON")
+
+
+class JobCompleteCompressedPayloadTests(unittest.IsolatedAsyncioTestCase):
+    codec = job_routes.transfer_codec
+
+    def setUp(self):
+        self.queue = asyncio.Queue()
+        job_routes.prompt_server.distributed_jobs_lock = asyncio.Lock()
+        job_routes.prompt_server.distributed_pending_jobs = {"job-z": self.queue}
+
+    def _frames(self, count=4, height=20, width=30):
+        rng = np.random.default_rng(1)
+        return rng.integers(0, 256, (count, height, width, 3), dtype=np.uint8)
+
+    def _request_for(self, frames, fmt, *, start_offset=0, is_last=True, audio=None, **overrides):
+        chunk = next(self.codec.encode_chunks(frames, fmt, 90, 10**9))
+        parts = chunk.pop("parts")
+        envelope = {
+            "job_id": "job-z",
+            "worker_id": "worker-1",
+            "is_last": is_last,
+            **chunk,
+            "start_index": chunk["start_index"] + start_offset,
+        }
+        if audio is not None:
+            envelope["audio"] = audio
+        envelope.update(overrides)
+        return _FakeMultipartRequest(envelope, parts)
+
+    async def _drain(self):
+        items = []
+        while not self.queue.empty():
+            items.append(await self.queue.get())
+        return items
+
+    async def test_lossless_chunk_enqueues_one_item_per_frame_bit_exact(self):
+        frames = self._frames()
+        response = await job_routes.job_complete_endpoint(self._request_for(frames, "ffv1", start_offset=10))
+
+        self.assertEqual(response.status, 200)
+        items = await self._drain()
+        self.assertEqual([item["image_index"] for item in items], [10, 11, 12, 13])
+        self.assertEqual([item["is_last"] for item in items], [False, False, False, True])
+        self.assertEqual({item["worker_id"] for item in items}, {"worker-1"})
+        for item, frame in zip(items, frames):
+            self.assertEqual(tuple(item["tensor"].shape), (1, 20, 30, 3))
+            self.assertEqual(item["tensor"].dtype, torch.float32)
+            expected = frame.astype(np.float32) / 255.0
+            self.assertTrue(np.array_equal(item["tensor"][0].numpy(), expected))
+
+    async def test_non_final_chunk_never_marks_worker_done(self):
+        response = await job_routes.job_complete_endpoint(
+            self._request_for(self._frames(count=2), "png", is_last=False)
+        )
+
+        self.assertEqual(response.status, 200)
+        self.assertFalse(any(item["is_last"] for item in await self._drain()))
+
+    async def test_audio_is_attached_only_to_final_frame(self):
+        audio = JobCompleteAudioPayloadTests._encoded_audio_payload(None)
+        response = await job_routes.job_complete_endpoint(
+            self._request_for(self._frames(count=3), "jpeg", audio=audio)
+        )
+
+        self.assertEqual(response.status, 200)
+        items = await self._drain()
+        self.assertEqual([item["audio"] is not None for item in items], [False, False, True])
+        self.assertEqual(tuple(items[-1]["audio"]["waveform"].shape), (1, 2, 4))
+
+    async def test_rejects_frame_count_mismatch(self):
+        response = await job_routes.job_complete_endpoint(
+            self._request_for(self._frames(count=2), "ffv1", count=5)
+        )
+
+        self.assertEqual(response.status, 400)
+        self.assertIn("frames", response.payload["message"])
+        self.assertTrue(self.queue.empty())
+
+    async def test_rejects_bad_envelope(self):
+        response = await job_routes.job_complete_endpoint(
+            self._request_for(self._frames(count=1), "png", format="gif", is_last="yes")
+        )
+
+        self.assertEqual(response.status, 400)
+        self.assertIn("format", response.payload["message"])
+        self.assertIn("is_last", response.payload["message"])
+
+    async def test_rejects_invalid_envelope_json(self):
+        response = await job_routes.job_complete_endpoint(_FakeMultipartRequest("{not json", [b"x"]))
+
+        self.assertEqual(response.status, 400)
+        self.assertIn("envelope", response.payload["message"])
+
+    async def test_unknown_job_returns_404(self):
+        job_routes.prompt_server.distributed_pending_jobs = {}
+        with patch.object(job_routes, "JOB_INIT_GRACE_PERIOD", 0.0):
+            response = await job_routes.job_complete_endpoint(self._request_for(self._frames(count=1), "png"))
+
+        self.assertEqual(response.status, 404)
+
+    async def test_legacy_json_payload_still_accepted(self):
+        request = _FakeRequest(
+            {
+                "job_id": "job-z",
+                "worker_id": "worker-1",
+                "batch_idx": 3,
+                "image": "data:image/png;base64,AAAA",
+                "is_last": True,
+            }
+        )
+        with patch.object(job_routes, "_decode_canonical_png_tensor", return_value="tensor-data"):
+            response = await job_routes.job_complete_endpoint(request)
+
+        self.assertEqual(response.status, 200)
+        items = await self._drain()
+        self.assertEqual(len(items), 1)
+        self.assertEqual((items[0]["image_index"], items[0]["tensor"]), (3, "tensor-data"))
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -164,26 +164,11 @@ class ConvertPathsForPlatformTests(unittest.TestCase):
 # ---------------------------------------------------------------------------

 class FindMediaReferencesTests(unittest.TestCase):
-    def test_finds_image_input(self):
-        prompt = {"1": {"class_type": "LoadImage", "inputs": {"image": "photo.png"}}}
-        refs = ms._find_media_references(prompt)
-        self.assertIn("photo.png", refs)
-
-    def test_finds_video_input(self):
-        prompt = {"1": {"class_type": "LoadVideo", "inputs": {"video": "clip.mp4"}}}
-        refs = ms._find_media_references(prompt)
-        self.assertIn("clip.mp4", refs)
-
    def test_finds_file_input_for_load_video(self):
        prompt = {"1": {"class_type": "LoadVideo", "inputs": {"file": "1 - Copy.mp4"}}}
        refs = ms._find_media_references(prompt)
        self.assertIn("1 - Copy.mp4", refs)

-    def test_finds_audio_input(self):
-        prompt = {"1": {"class_type": "LoadAudio", "inputs": {"audio": "track.wav"}}}
-        refs = ms._find_media_references(prompt)
-        self.assertIn("track.wav", refs)
-
    def test_strips_annotation_suffix(self):
        prompt = {"1": {"class_type": "LoadImage", "inputs": {"image": "photo.jpg [abc123]"}}}
        refs = ms._find_media_references(prompt)
@@ -0,0 +1,216 @@
+"""End-to-end: real worker send path -> real aiohttp server -> job_complete endpoint."""
+import asyncio
+import importlib.util
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+import torch
+
+_TESTS_DIR = Path(__file__).resolve().parents[1]
+
+
+def _load_from(path, name):
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _load_modules():
+    real_aiohttp = sys.modules["aiohttp"]  # imported inside the isolated test
+    queue_tests = _load_from(_TESTS_DIR / "api" / "test_distributed_queue.py", "dist_transfer_it_queue")
+    collector_tests = _load_from(_TESTS_DIR / "test_collector_list_inputs.py", "dist_transfer_it_collector")
+    job_routes = queue_tests._load_job_routes_module()
+    collector = collector_tests._load_collector_module()
+
+    # Error responses must be real HTTP responses here (the unit-test harness
+    # returns plain objects); mirror utils.network.handle_api_error.
+    from aiohttp import web
+
+    async def handle_api_error(_request, error, status=500):
+        if isinstance(error, list):
+            return web.json_response({"errors": [str(item) for item in error]}, status=status)
+        return web.json_response({"error": str(error)}, status=status)
+
+    job_routes.handle_api_error = handle_api_error
+    # The collector harness stubs aiohttp; this test needs the real client.
+    sys.modules["aiohttp"] = real_aiohttp
+    collector.aiohttp = real_aiohttp
+    return job_routes, collector
+
+
+@pytest.fixture(autouse=True)
+def _isolate_sys_modules():
+    """The loaders below install stub modules (server, comfy, aiohttp...); undo that."""
+    saved = dict(sys.modules)
+    # Earlier test modules may have left a stub `aiohttp` behind; drop it so the
+    # real package is imported for this test (restored afterwards).
+    for name in [n for n in sys.modules if n == "aiohttp" or n.startswith("aiohttp.")]:
+        if getattr(sys.modules[name], "__file__", None) is None:
+            del sys.modules[name]
+    yield
+    sys.modules.clear()
+    sys.modules.update(saved)
+
+
+async def _run_transfer(job_routes, collector_module, images, fmt, *, client_max_size,
+                        request_limit, chunk_target, audio=None):
+    """Send `images` from a real worker node to the real completion route.
+
+    Returns (queued items, sizes of every request body the server received,
+    exception raised by the worker or None).
+    """
+    import aiohttp
+    from aiohttp import web
+
+    queue = asyncio.Queue()
+    job_routes.prompt_server.distributed_jobs_lock = asyncio.Lock()
+    job_routes.prompt_server.distributed_pending_jobs = {"job-it": queue}
+    body_sizes = []
+
+    @web.middleware
+    async def record_size(request, handler):
+        body_sizes.append(request.content_length)
+        return await handler(request)
+
+    app = web.Application(client_max_size=client_max_size, middlewares=[record_size])
+    app.router.add_post("/distributed/job_complete", job_routes.job_complete_endpoint)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    port = site._server.sockets[0].getsockname()[1]
+
+    error = None
+    try:
+        async with aiohttp.ClientSession() as session:
+            async def _get_session():
+                return session
+
+            collector_module.get_client_session = _get_session
+            collector_module.TRANSFER_MAX_REQUEST_BYTES = request_limit
+            collector_module.TRANSFER_MAX_CHUNK_BYTES = chunk_target
+            node = collector_module.DistributedCollectorNode()
+            try:
+                await node.send_batch_to_master(
+                    images, audio, "job-it", f"http://127.0.0.1:{port}", "worker-1", fmt, 90
+                )
+            except Exception as exc:  # surfaced to the caller for assertions
+                error = exc
+    finally:
+        await runner.cleanup()
+
+    items = []
+    while not queue.empty():
+        items.append(queue.get_nowait())
+    return items, body_sizes, error
+
+
+def _noise_images(count, height=360, width=640, seed=97):
+    return torch.from_numpy(np.random.default_rng(seed).random((count, height, width, 3), dtype=np.float32))
+
+
+@pytest.mark.parametrize("fmt", ["h264", "ffv1"])
+def test_high_entropy_video_stays_under_server_upload_limit(fmt):
+    """Encoder flush used to push finalized chunks past the limit (HTTP 400)."""
+    pytest.importorskip("aiohttp")
+    job_routes, collector_module = _load_modules()
+    images = _noise_images(24)
+    limit = 2 * 1024 * 1024
+    reserve = collector_module.DistributedCollectorNode.TRANSFER_ENVELOPE_RESERVE_BYTES
+
+    items, body_sizes, error = asyncio.run(_run_transfer(
+        job_routes, collector_module, images, fmt,
+        client_max_size=limit, request_limit=limit, chunk_target=limit - reserve))
+
+    assert error is None, error
+    assert len(body_sizes) > 1 and max(body_sizes) <= limit
+    assert [item["image_index"] for item in items] == list(range(24))
+    assert [item["is_last"] for item in items] == [False] * 23 + [True]
+
+
+def test_server_rejection_for_size_is_reported_not_retried_as_legacy():
+    """A worker configured above the master's limit fails loudly instead of
+    silently resending the whole batch as uncompressed PNG."""
+    pytest.importorskip("aiohttp")
+    job_routes, collector_module = _load_modules()
+    images = _noise_images(8)
+
+    items, body_sizes, error = asyncio.run(_run_transfer(
+        job_routes, collector_module, images, "ffv1",
+        client_max_size=1024 * 1024, request_limit=8 * 1024 * 1024, chunk_target=4 * 1024 * 1024))
+
+    assert isinstance(error, RuntimeError)
+    assert "HTTP 413" in str(error) and "--max-upload-size" in str(error)
+    assert len(body_sizes) == 1
+    assert items == []
+
+
+def test_frame_that_cannot_fit_sends_nothing():
+    pytest.importorskip("aiohttp")
+    job_routes, collector_module = _load_modules()
+    images = _noise_images(3)
+    reserve = collector_module.DistributedCollectorNode.TRANSFER_ENVELOPE_RESERVE_BYTES
+
+    items, body_sizes, error = asyncio.run(_run_transfer(
+        job_routes, collector_module, images, "png",
+        client_max_size=100 * 1024 * 1024, request_limit=reserve + 64 * 1024, chunk_target=64 * 1024))
+
+    assert isinstance(error, collector_module.transfer_codec.FrameTooLargeError)
+    assert body_sizes == []
+    assert items == []
+
+
+@pytest.mark.parametrize("fmt", ["png", "ffv1", "h264", "jpeg"])
+def test_worker_to_master_over_real_http(fmt):
+    # Import here, not at module level: other test harnesses only install their
+    # aiohttp stubs when the real package has not been imported yet.
+    aiohttp = pytest.importorskip("aiohttp")
+    from aiohttp import web
+
+    job_routes, collector_module = _load_modules()
+    images = torch.rand(5, 24, 36, 3)
+
+    async def scenario():
+        queue = asyncio.Queue()
+        job_routes.prompt_server.distributed_jobs_lock = asyncio.Lock()
+        job_routes.prompt_server.distributed_pending_jobs = {"job-it": queue}
+
+        app = web.Application()
+        app.router.add_post("/distributed/job_complete", job_routes.job_complete_endpoint)
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, "127.0.0.1", 0)
+        await site.start()
+        port = site._server.sockets[0].getsockname()[1]
+
+        async with aiohttp.ClientSession() as session:
+            async def _get_session():
+                return session
+
+            collector_module.get_client_session = _get_session
+            collector_module.TRANSFER_MAX_CHUNK_BYTES = 2000  # several requests for still formats
+            node = collector_module.DistributedCollectorNode()
+            await node.send_batch_to_master(
+                images, None, "job-it", f"http://127.0.0.1:{port}", "worker-1", fmt, 90
+            )
+        await runner.cleanup()
+
+        items = []
+        while not queue.empty():
+            items.append(queue.get_nowait())
+        return items
+
+    items = asyncio.run(scenario())
+
+    assert [item["image_index"] for item in items] == [0, 1, 2, 3, 4]
+    assert [item["is_last"] for item in items] == [False, False, False, False, True]
+    expected = np.clip(255.0 * images.numpy(), 0, 255).astype(np.uint8).astype(np.float32) / 255.0
+    got = torch.cat([item["tensor"] for item in items]).numpy()
+    assert got.shape == expected.shape
+    if fmt in ("png", "ffv1"):
+        assert np.array_equal(got, expected)
+    else:
+        assert np.abs(got - expected).mean() < 0.25  # random noise: only sanity-check lossy codecs
@@ -106,7 +106,7 @@ def _load_worker_routes_module():
    sys.modules[f"{package_name}.utils"] = utils_pkg

    workers_pkg = types.ModuleType(f"{package_name}.workers")
-    workers_pkg.__path__ = []
+    workers_pkg.__path__ = [str(module_path.parents[1] / "workers")]
    workers_pkg.get_worker_manager = lambda: _DummyWorkerManager()
    sys.modules[f"{package_name}.workers"] = workers_pkg

@@ -213,6 +213,7 @@ def _load_worker_routes_module():
        raise RuntimeError("not used in these tests")

    network_module.get_client_session = _get_client_session
+    network_module.get_server_port = lambda: 8189
    sys.modules[f"{package_name}.utils.network"] = network_module

    constants_module = types.ModuleType(f"{package_name}.utils.constants")
@@ -269,6 +270,38 @@ worker_routes = _load_worker_routes_module()


 class WorkerRoutesTests(unittest.IsolatedAsyncioTestCase):
+    async def test_network_info_reports_actual_master_and_available_ports(self):
+        with patch.object(worker_routes, "_get_cuda_info", return_value=(0, 1, 4)), \
+             patch.object(worker_routes, "get_network_ips", return_value=["127.0.0.1"]), \
+             patch.object(worker_routes, "load_config", return_value={"workers": []}), \
+             patch.object(worker_routes, "get_server_port", return_value=8189), \
+             patch.object(worker_routes, "allocate_worker_ports", return_value=[8191, 8192, 8193]) as allocate:
+            response = await worker_routes.get_network_info_endpoint(_FakeRequest())
+        self.assertEqual(response.payload["master_port"], 8189)
+        self.assertEqual(response.payload["local_worker_ports"], [8191, 8192, 8193])
+        self.assertEqual(response.payload["cuda_device_count"], 4)
+        allocate.assert_called_once_with(8189, [], 3)
+
+    async def test_network_info_does_not_reallocate_existing_configuration(self):
+        with patch.object(worker_routes, "_get_cuda_info", return_value=(0, 4, 4)), \
+             patch.object(worker_routes, "get_network_ips", return_value=[]), \
+             patch.object(worker_routes, "load_config", return_value={"workers": [{"id": "existing", "port": 8189}]}), \
+             patch.object(worker_routes, "allocate_worker_ports") as allocate:
+            response = await worker_routes.get_network_info_endpoint(_FakeRequest())
+        self.assertEqual(response.payload["local_worker_ports"], [])
+        allocate.assert_not_called()
+
+    async def test_launch_conflict_is_a_clear_client_error(self):
+        manager = _DummyWorkerManager()
+        config = {"workers": [{"id": "worker-a", "name": "Worker A", "port": 8189}]}
+        with patch.object(worker_routes, "get_worker_manager", return_value=manager), \
+             patch.object(worker_routes, "load_config", return_value=config), \
+             patch.object(manager, "launch_worker", side_effect=ValueError("Worker port 8189 conflicts with the master port 8189")):
+            response = await worker_routes.launch_worker_endpoint(_FakeRequest({"worker_id": "worker-a"}))
+        self.assertEqual(response.status, 400)
+        self.assertIn("master port 8189", response.payload["message"])
+        self.assertEqual(manager.processes, {})
+
    async def test_launch_worker_valid_id_returns_200(self):
        manager = _DummyWorkerManager()
        config = {"workers": [{"id": "worker-a", "name": "Worker A", "port": 8188}]}
@@ -0,0 +1,691 @@
+{
+  "DistributedCollector": {
+    "input": {
+      "required": {
+        "load_balance": [
+          "BOOLEAN",
+          {
+            "default": false,
+            "tooltip": "Run this workflow on one least-busy participant (master included when participating)."
+          }
+        ]
+      },
+      "optional": {
+        "images": [
+          "IMAGE"
+        ],
+        "audio": [
+          "AUDIO"
+        ]
+      },
+      "hidden": {
+        "multi_job_id": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "is_worker": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ],
+        "master_url": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "enabled_worker_ids": [
+          "STRING",
+          {
+            "default": "[]"
+          }
+        ],
+        "worker_batch_size": [
+          "INT",
+          {
+            "default": 1,
+            "min": 1,
+            "max": 1024
+          }
+        ],
+        "worker_id": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "pass_through": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ],
+        "delegate_only": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "load_balance"
+      ],
+      "optional": [
+        "images",
+        "audio"
+      ],
+      "hidden": [
+        "multi_job_id",
+        "is_worker",
+        "master_url",
+        "enabled_worker_ids",
+        "worker_batch_size",
+        "worker_id",
+        "pass_through",
+        "delegate_only"
+      ]
+    },
+    "output": [
+      "IMAGE",
+      "AUDIO"
+    ],
+    "output_name": [
+      "images",
+      "audio"
+    ],
+    "output_is_list": [
+      false,
+      false
+    ],
+    "is_input_list": true,
+    "output_node": false,
+    "category": "image",
+    "display_name": "Distributed Collector"
+  },
+  "DistributedSeed": {
+    "input": {
+      "required": {
+        "seed": [
+          "INT",
+          {
+            "default": 1125899906842,
+            "min": 0,
+            "max": 1125899906842624,
+            "forceInput": false
+          }
+        ]
+      },
+      "hidden": {
+        "is_worker": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ],
+        "worker_id": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "seed"
+      ],
+      "hidden": [
+        "is_worker",
+        "worker_id"
+      ]
+    },
+    "output": [
+      "INT"
+    ],
+    "output_name": [
+      "seed"
+    ],
+    "output_is_list": [
+      false
+    ],
+    "is_input_list": false,
+    "output_node": false,
+    "category": "utils",
+    "display_name": "Distributed Seed"
+  },
+  "DistributedModelName": {
+    "input": {
+      "required": {
+        "text": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ]
+      },
+      "hidden": {
+        "unique_id": "UNIQUE_ID",
+        "extra_pnginfo": "EXTRA_PNGINFO"
+      }
+    },
+    "input_order": {
+      "required": [
+        "text"
+      ],
+      "hidden": [
+        "unique_id",
+        "extra_pnginfo"
+      ]
+    },
+    "output": [
+      "*"
+    ],
+    "output_name": [
+      "output"
+    ],
+    "output_is_list": [
+      false
+    ],
+    "is_input_list": false,
+    "output_node": true,
+    "category": "utils",
+    "display_name": "Distributed Model Name"
+  },
+  "DistributedValue": {
+    "input": {
+      "required": {
+        "default_value": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "worker_values": [
+          "STRING",
+          {
+            "default": "{}"
+          }
+        ]
+      },
+      "hidden": {
+        "is_worker": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ],
+        "worker_id": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "default_value",
+        "worker_values"
+      ],
+      "hidden": [
+        "is_worker",
+        "worker_id"
+      ]
+    },
+    "output": [
+      "*"
+    ],
+    "output_name": [
+      "value"
+    ],
+    "output_is_list": [
+      false
+    ],
+    "is_input_list": false,
+    "output_node": false,
+    "category": "utils",
+    "display_name": "Distributed Value"
+  },
+  "ImageBatchDivider": {
+    "input": {
+      "required": {
+        "images": [
+          "IMAGE"
+        ],
+        "divide_by": [
+          "INT",
+          {
+            "default": 2,
+            "min": 1,
+            "max": 10,
+            "step": 1,
+            "display": "number",
+            "tooltip": "Number of parts to divide the batch into"
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "images",
+        "divide_by"
+      ]
+    },
+    "output": [
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*"
+    ],
+    "output_name": [
+      "batch_1",
+      "batch_2",
+      "batch_3",
+      "batch_4",
+      "batch_5",
+      "batch_6",
+      "batch_7",
+      "batch_8",
+      "batch_9",
+      "batch_10"
+    ],
+    "output_is_list": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ],
+    "is_input_list": false,
+    "output_node": true,
+    "category": "image",
+    "display_name": "Image Batch Divider"
+  },
+  "AudioBatchDivider": {
+    "input": {
+      "required": {
+        "audio": [
+          "AUDIO"
+        ],
+        "divide_by": [
+          "INT",
+          {
+            "default": 2,
+            "min": 1,
+            "max": 10,
+            "step": 1,
+            "display": "number",
+            "tooltip": "Number of sequential time segments to create"
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "audio",
+        "divide_by"
+      ]
+    },
+    "output": [
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*",
+      "*"
+    ],
+    "output_name": [
+      "audio_1",
+      "audio_2",
+      "audio_3",
+      "audio_4",
+      "audio_5",
+      "audio_6",
+      "audio_7",
+      "audio_8",
+      "audio_9",
+      "audio_10"
+    ],
+    "output_is_list": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ],
+    "is_input_list": false,
+    "output_node": true,
+    "category": "audio",
+    "display_name": "Audio Segment Divider"
+  },
+  "DistributedEmptyImage": {
+    "input": {
+      "required": {
+        "height": [
+          "INT",
+          {
+            "default": 64,
+            "min": 1,
+            "max": 4096,
+            "step": 1
+          }
+        ],
+        "width": [
+          "INT",
+          {
+            "default": 64,
+            "min": 1,
+            "max": 4096,
+            "step": 1
+          }
+        ],
+        "channels": [
+          "INT",
+          {
+            "default": 3,
+            "min": 1,
+            "max": 4,
+            "step": 1
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "height",
+        "width",
+        "channels"
+      ]
+    },
+    "output": [
+      "IMAGE"
+    ],
+    "output_name": [
+      "IMAGE"
+    ],
+    "output_is_list": [
+      false
+    ],
+    "is_input_list": false,
+    "output_node": false,
+    "category": "image",
+    "display_name": "Distributed Empty Image"
+  },
+  "UltimateSDUpscaleDistributed": {
+    "input": {
+      "required": {
+        "upscaled_image": [
+          "IMAGE"
+        ],
+        "model": [
+          "MODEL"
+        ],
+        "positive": [
+          "CONDITIONING"
+        ],
+        "negative": [
+          "CONDITIONING"
+        ],
+        "vae": [
+          "VAE"
+        ],
+        "seed": [
+          "INT",
+          {
+            "default": 0,
+            "min": 0,
+            "max": 18446744073709551615
+          }
+        ],
+        "steps": [
+          "INT",
+          {
+            "default": 20,
+            "min": 1,
+            "max": 10000
+          }
+        ],
+        "cfg": [
+          "FLOAT",
+          {
+            "default": 8.0,
+            "min": 0.0,
+            "max": 100.0
+          }
+        ],
+        "sampler_name": [
+          [
+            "euler",
+            "euler_cfg_pp",
+            "euler_ancestral",
+            "euler_ancestral_cfg_pp",
+            "heun",
+            "heunpp2",
+            "exp_heun_2_x0",
+            "exp_heun_2_x0_sde",
+            "dpm_2",
+            "dpm_2_ancestral",
+            "lms",
+            "dpm_fast",
+            "dpm_adaptive",
+            "dpmpp_2s_ancestral",
+            "dpmpp_2s_ancestral_cfg_pp",
+            "dpmpp_sde",
+            "dpmpp_sde_gpu",
+            "dpmpp_2m",
+            "dpmpp_2m_cfg_pp",
+            "dpmpp_2m_sde",
+            "dpmpp_2m_sde_gpu",
+            "dpmpp_2m_sde_heun",
+            "dpmpp_2m_sde_heun_gpu",
+            "dpmpp_3m_sde",
+            "dpmpp_3m_sde_gpu",
+            "ddpm",
+            "lcm",
+            "ipndm",
+            "ipndm_v",
+            "deis",
+            "cfgpp_ud10_ab",
+            "res_multistep",
+            "res_multistep_cfg_pp",
+            "res_multistep_ancestral",
+            "res_multistep_ancestral_cfg_pp",
+            "gradient_estimation",
+            "gradient_estimation_cfg_pp",
+            "er_sde",
+            "seeds_2",
+            "seeds_3",
+            "sa_solver",
+            "sa_solver_pece",
+            "ddim",
+            "uni_pc",
+            "uni_pc_bh2"
+          ]
+        ],
+        "scheduler": [
+          [
+            "simple",
+            "sgm_uniform",
+            "karras",
+            "exponential",
+            "ddim_uniform",
+            "beta",
+            "normal",
+            "linear_quadratic",
+            "kl_optimal"
+          ]
+        ],
+        "denoise": [
+          "FLOAT",
+          {
+            "default": 0.5,
+            "min": 0.0,
+            "max": 1.0,
+            "step": 0.01
+          }
+        ],
+        "tile_width": [
+          "INT",
+          {
+            "default": 512,
+            "min": 64,
+            "max": 2048,
+            "step": 8
+          }
+        ],
+        "tile_height": [
+          "INT",
+          {
+            "default": 512,
+            "min": 64,
+            "max": 2048,
+            "step": 8
+          }
+        ],
+        "padding": [
+          "INT",
+          {
+            "default": 32,
+            "min": 0,
+            "max": 256,
+            "step": 8
+          }
+        ],
+        "mask_blur": [
+          "INT",
+          {
+            "default": 8,
+            "min": 0,
+            "max": 256
+          }
+        ],
+        "force_uniform_tiles": [
+          "BOOLEAN",
+          {
+            "default": true
+          }
+        ],
+        "tiled_decode": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ]
+      },
+      "hidden": {
+        "multi_job_id": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "is_worker": [
+          "BOOLEAN",
+          {
+            "default": false
+          }
+        ],
+        "master_url": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "enabled_worker_ids": [
+          "STRING",
+          {
+            "default": "[]"
+          }
+        ],
+        "worker_id": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "tile_indices": [
+          "STRING",
+          {
+            "default": ""
+          }
+        ],
+        "dynamic_threshold": [
+          "INT",
+          {
+            "default": 8,
+            "min": 1,
+            "max": 64
+          }
+        ]
+      }
+    },
+    "input_order": {
+      "required": [
+        "upscaled_image",
+        "model",
+        "positive",
+        "negative",
+        "vae",
+        "seed",
+        "steps",
+        "cfg",
+        "sampler_name",
+        "scheduler",
+        "denoise",
+        "tile_width",
+        "tile_height",
+        "padding",
+        "mask_blur",
+        "force_uniform_tiles",
+        "tiled_decode"
+      ],
+      "hidden": [
+        "multi_job_id",
+        "is_worker",
+        "master_url",
+        "enabled_worker_ids",
+        "worker_id",
+        "tile_indices",
+        "dynamic_threshold"
+      ]
+    },
+    "output": [
+      "IMAGE"
+    ],
+    "output_name": [
+      "IMAGE"
+    ],
+    "output_is_list": [
+      false
+    ],
+    "is_input_list": false,
+    "output_node": false,
+    "category": "image/upscaling",
+    "display_name": "Ultimate SD Upscale Distributed (No Upscale)"
+  }
+}
@@ -0,0 +1,289 @@
+"""Exercise the actual loader, schemas and executor in a fresh CPU process.
+
+No HTTP listener, workers, model downloads or live installation changes.
+The original contracts were captured from 32ac027 using the same core.
+"""
+import asyncio
+import inspect
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+from unittest.mock import patch
+
+from PIL import Image
+
+ROOT = Path(__file__).resolve().parents[2]
+COMFY_ROOT = Path(sys.argv[1]).resolve()
+sys.path.insert(0, str(COMFY_ROOT))
+os.environ['COMFYUI_IS_WORKER'] = '1'
+import comfy.cli_args
+comfy.cli_args.args.cpu = True
+comfy.cli_args.args.disable_assets = True
+from app.assets.manager import default_asset_manager
+from comfy_api.v0_0_2 import io
+import execution
+import nodes
+import server
+import torch
+
+BASELINE = json.loads((ROOT / 'tests/fixtures/v1_node_contracts.json').read_text())
+
+# Inputs intentionally added after the V1 baseline was captured. They must be
+# optional, appended after the baseline inputs, and keep legacy behaviour as
+# their default so saved workflows are unaffected.
+ADDED_OPTIONAL_INPUTS = {
+    'DistributedCollector': {
+        'transfer_format': [
+            ['legacy_png', 'png', 'ffv1', 'jpeg', 'webp', 'h264', 'h265', 'av1'],
+            {'default': 'legacy_png'},
+        ],
+        'transfer_quality': ['INT', {'default': 90, 'min': 1, 'max': 100, 'step': 1}],
+    },
+}
+
+
+def normalized_input(value):
+    kind = value[0]
+    opts = dict(value[1]) if len(value) > 1 else {}
+    if kind == 'STRING':
+        # V3 serializes the same default single-line widget explicitly.
+        opts.setdefault('multiline', False)
+    if kind == 'COMBO':
+        kind = opts['options']
+        opts = {key: val for key, val in opts.items() if key != 'options'}
+    if isinstance(kind, list):
+        # Single-selection is the V1 dropdown default as well.
+        opts.setdefault('multiselect', False)
+    return [kind, opts]
+
+
+async def map_node(cls, values, extra=None):
+    """Use the actual input parser and sanitized V3 executor clones."""
+    prepared, missing, hidden = execution.get_input_data(values, cls, unique_id='probe', extra_data=extra or {})
+    assert not missing, missing
+    # Use a worker thread for synchronous nodes: collector/upscale bridge back
+    # to PromptServer's running loop, just as ComfyUI's prompt worker does.
+    def run():
+        return asyncio.run(execution._async_map_node_over_list(
+            'v3-acceptance', 'probe', cls, prepared, cls.FUNCTION, v3_data=hidden))
+    return await asyncio.to_thread(run)
+
+
+def check_saved_workflows(mapping):
+    checked = 0
+    occurrences = 0
+    for path in sorted((ROOT / 'workflows').glob('*.json')):
+        workflow = json.loads(path.read_text())
+        local_nodes = {node['id']: node for node in workflow['nodes']}
+        for saved in workflow['nodes']:
+            if saved['type'] not in mapping:
+                continue
+            occurrences += 1
+            info = mapping[saved['type']].GET_NODE_INFO_V1()
+            inputs = {**info['input'].get('required', {}), **info['input'].get('optional', {})}
+            for socket in saved.get('inputs', []):
+                assert socket['name'] in inputs, (path.name, saved['id'], socket)
+                assert socket['type'] == inputs[socket['name']][0], (path.name, socket)
+            for index, output in enumerate(saved.get('outputs', [])):
+                assert output['type'] == info['output'][index], (path.name, index)
+            for link in workflow['links']:
+                if link[1] == saved['id']:
+                    assert link[2] < len(info['output']), (path.name, link)
+                    target = local_nodes[link[3]]['inputs'][link[4]]
+                    assert target['type'] == info['output'][link[2]], (path.name, link)
+        checked += 1
+    assert checked == 5 and occurrences == 10, (checked, occurrences)
+    print('SAVED_WORKFLOW_CONTRACTS_OK', checked, occurrences)
+
+
+async def check_execution(mapping, module, prompt_server, asset_manager):
+    result = await map_node(mapping['DistributedSeed'],
+                            {'seed': 123, 'is_worker': True, 'worker_id': 'worker_2'})
+    assert result[0].result == (126,)
+    values = json.dumps({'_type': 'INT', '3': '17'})
+    result = await map_node(mapping['DistributedValue'],
+                            {'default_value': '4', 'worker_values': values,
+                             'is_worker': True, 'worker_id': 'worker_2'})
+    assert result[0].result == (17,)
+    metadata = {'workflow': {'nodes': [{'id': 'probe', 'widgets_values': []}]}}
+    result = await map_node(mapping['DistributedModelName'], {'text': 'model.ckpt'},
+                            {'extra_pnginfo': metadata})
+    assert result[0].result == ('model.ckpt',)
+    assert result[0].ui == {'text': ['model.ckpt']}
+    assert metadata['workflow']['nodes'][0]['widgets_values'] == [['model.ckpt']]
+    result = await map_node(mapping['DistributedEmptyImage'],
+                            {'height': 8, 'width': 8, 'channels': 3})
+    empty = result[0].result[0]
+    assert empty.shape == (0, 8, 8, 3) and empty.numel() == 0
+    images = torch.arange(10 * 8 * 8 * 3, dtype=torch.float32).reshape(10, 8, 8, 3)
+    for count in (1, 3, 10):
+        result = await map_node(mapping['ImageBatchDivider'], {'images': images, 'divide_by': count})
+        assert len(result[0].result) == 10
+        assert torch.equal(torch.cat(result[0].result[:count]), images)
+    audio = {'waveform': torch.arange(33, dtype=torch.float32).reshape(1, 1, 33), 'sample_rate': 24000}
+    result = await map_node(mapping['AudioBatchDivider'], {'audio': audio, 'divide_by': 3})
+    assert len(result[0].result) == 10
+    assert torch.equal(torch.cat([item['waveform'] for item in result[0].result[:3]], dim=-1), audio['waveform'])
+    # INPUT_IS_LIST must preserve all images/audio but unwrap transport scalars.
+    collector = mapping['DistributedCollector']
+    prepared, missing, hidden = execution.get_input_data(
+        {'load_balance': False, 'multi_job_id': '', 'pass_through': True}, collector, 'collector-list')
+    assert not missing
+    prepared['images'] = [images[:2], images[2:]]
+    prepared['audio'] = [audio, audio]
+    result = await execution._async_map_node_over_list(
+        'v3-acceptance', 'collector-list', collector, prepared, collector.FUNCTION, v3_data=hidden)
+    assert torch.equal(result[0].result[0], images)
+    assert result[0].result[1]['waveform'].shape[-1] == 66
+    # Exercise real async aggregation without an HTTP endpoint or worker.
+    queue = asyncio.Queue()
+    await queue.put({'worker_id': 'worker_2', 'tensor': images[2:3], 'image_index': 0, 'is_last': True})
+    prompt_server.distributed_pending_jobs['v3-aggregate'] = queue
+    result = await map_node(collector,
+                            {'images': images[:2], 'load_balance': False,
+                             'multi_job_id': 'v3-aggregate', 'enabled_worker_ids': '["worker_2"]'})
+    assert torch.equal(result[0].result[0], images[:3])
+    assert 'v3-aggregate' not in prompt_server.distributed_pending_jobs
+
+    # The registered node must forward the transfer options to the runtime
+    # helper, and default to the legacy transfer when they are not set.
+    collector_runtime = sys.modules[module.__name__ + '.nodes.collector'].DistributedCollectorNode
+    forwarded = []
+    def fake_run(self, **kwargs):
+        forwarded.append(kwargs)
+        return (kwargs['images'], kwargs['audio'])
+    with patch.object(collector_runtime, 'run', fake_run):
+        await map_node(collector, {'images': images[:1], 'load_balance': False, 'pass_through': True,
+                                   'transfer_format': 'av1', 'transfer_quality': 70})
+        await map_node(collector, {'images': images[:1], 'load_balance': False, 'pass_through': True})
+    # Set values arrive list-wrapped (is_input_list); unset ones use the
+    # execute() defaults. The runtime helper unwraps both forms.
+    assert [(kw['transfer_format'], kw['transfer_quality']) for kw in forwarded] == [
+        (['av1'], [70]), ('legacy_png', 90)], forwarded
+
+    # Prove V3's per-execution class clones do not leak helper instance state;
+    # replace only the GPU/model boundary, not the input parser or executor.
+    upscale_runtime = sys.modules[module.__name__ + '.nodes.distributed_upscale'].UltimateSDUpscaleDistributed
+    seen = []
+    def fake_upscale(self, *args):
+        assert not hasattr(self, 'acceptance_marker')
+        self.acceptance_marker = True
+        seen.append(args)
+        return (args[0],)
+    inputs = {'upscaled_image': images, 'model': object(), 'positive': [], 'negative': [],
+              'vae': object(), 'seed': 1, 'steps': 1, 'cfg': 1.0,
+              'sampler_name': 'euler', 'scheduler': 'normal', 'denoise': 0.5,
+              'tile_width': 64, 'tile_height': 64, 'padding': 0, 'mask_blur': 0,
+              'force_uniform_tiles': True, 'tiled_decode': False,
+              'multi_job_id': 'tile-job', 'is_worker': True, 'master_url': 'http://master.invalid',
+              'enabled_worker_ids': '["worker_2"]', 'worker_id': 'worker_2',
+              'tile_indices': '[2,3]', 'dynamic_threshold': 9}
+    with patch.object(upscale_runtime, 'run', fake_upscale):
+        for _ in range(2):
+            result = await map_node(mapping['UltimateSDUpscaleDistributed'], inputs)
+            assert result[0].result[0] is images
+    assert len(seen) == 2 and seen[0][-7:] == tuple(inputs[name] for name in (
+        'multi_job_id', 'is_worker', 'master_url', 'enabled_worker_ids', 'worker_id',
+        'tile_indices', 'dynamic_threshold')), seen[0]
+    import math
+    assert math.isnan(mapping['UltimateSDUpscaleDistributed'].fingerprint_inputs(multi_job_id='tile-job'))
+    assert math.isnan(mapping['UltimateSDUpscaleDistributed'].fingerprint_inputs(multi_job_id=''))
+
+    graph = {
+        '1': {'class_type': 'EmptyImage', 'inputs': {'height': 8, 'width': 8, 'batch_size': 10, 'color': 0}},
+        '2': {'class_type': 'DistributedCollector', 'inputs': {'images': ['1', 0], 'load_balance': False,
+                                                              'pass_through': True}},
+        '3': {'class_type': 'ImageBatchDivider', 'inputs': {'images': ['2', 0], 'divide_by': 10}},
+        '4': {'class_type': 'PreviewImage', 'inputs': {'images': ['3', 9]}},
+    }
+    valid = await execution.validate_prompt('v3-graph', graph, None)
+    assert valid[0], valid
+    invalid = {'1': {'class_type': 'UltimateSDUpscaleDistributed',
+                     'inputs': {**inputs, 'sampler_name': 'INVALID_ENUM', 'scheduler': 'INVALID_ENUM'}},
+               '2': {'class_type': 'PreviewImage', 'inputs': {'images': ['1', 0]}}}
+    rejected = await execution.validate_prompt('v3-invalid', invalid, None)
+    assert not rejected[0]
+    errors = [error for entry in rejected[3].values() for error in entry['errors']]
+    enum_errors = [error['extra_info']['input_name'] for error in errors if error['type'] == 'value_not_in_list']
+    assert {'sampler_name', 'scheduler'} <= set(enum_errors), errors
+    import folder_paths
+    scratch = Path(os.environ.get('TMPDIR', Path.home() / '.hermes/cache/scratch'))
+    with tempfile.TemporaryDirectory(prefix='v3-preview-', dir=scratch) as temp:
+        with patch.object(folder_paths, 'temp_directory', temp):
+            executor = execution.PromptExecutor(
+                prompt_server, cache_args={'ram': 0, 'ram_inactive': 0}, asset_manager=asset_manager)
+            await asyncio.to_thread(executor.execute, graph, 'v3-graph', {}, valid[2])
+            assert executor.success, executor.status_messages
+            history = executor.history_result
+            record = history['outputs']['4']['images'][0]
+            preview = Path(temp) / record.get('subfolder', '') / record['filename']
+            with Image.open(preview) as image:
+                assert image.size == (8, 8) and image.mode == 'RGB'
+                assert image.getextrema() == ((0, 0), (0, 0), (0, 0))
+    print('V3_EXECUTION_OK eight nodes; upscale GPU boundary mocked; preview artifact verified')
+
+
+async def main():
+    asset_manager = default_asset_manager()
+    prompt_server = server.PromptServer(asyncio.get_running_loop(), asset_manager)
+    assert not (ROOT / 'distributed.py').exists(), 'obsolete root bootstrap remains'
+    assert await nodes.load_custom_node(str(ROOT)), 'ComfyUI loader rejected the pack'
+    module = sys.modules[str(ROOT).replace('.', '_x_')]
+    assert not hasattr(module, 'NODE_CLASS_MAPPINGS'), 'V1 map shadows V3 entrypoint'
+    extension = await module.comfy_entrypoint()
+    classes = await extension.get_node_list()
+    mapping = {cls.GET_SCHEMA().node_id: cls for cls in classes}
+    assert len(classes) == len(mapping) == len(BASELINE) == 8
+    assert set(mapping) == set(BASELINE)
+    for node_id, cls in mapping.items():
+        assert issubclass(cls, io.ComfyNode)
+        assert nodes.NODE_CLASS_MAPPINGS[node_id] is cls
+        old = dict(BASELINE[node_id])
+        if node_id in ('ImageBatchDivider', 'AudioBatchDivider'):
+            # V1's ByPassTypeTuple advertises '*' when indexed, while its
+            # underlying tuple and existing frontend declare IMAGE/AUDIO.
+            # Native V3 declares all ten existing typed sockets explicitly.
+            assert old['output'] == ['*'] * 10
+            old['output'] = ['IMAGE' if node_id == 'ImageBatchDivider' else 'AUDIO'] * 10
+        new = json.loads(json.dumps(cls.GET_NODE_INFO_V1()))
+        for group in ('required', 'optional'):
+            old_inputs = old['input'].get(group, {})
+            new_inputs = dict(new['input'].get(group, {}))
+            if group == 'optional':
+                for name, expected in ADDED_OPTIONAL_INPUTS.get(node_id, {}).items():
+                    assert name in new_inputs, (node_id, name, 'added input missing')
+                    actual = normalized_input(new_inputs.pop(name))
+                    kind, opts = normalized_input(expected)
+                    assert actual[0] == kind, (node_id, name, actual)
+                    for key, value in opts.items():
+                        assert actual[1].get(key) == value, (node_id, name, key, actual)
+            assert list(old_inputs) == list(new_inputs), (node_id, group, 'input order')
+            for name, original in old_inputs.items():
+                assert normalized_input(original) == normalized_input(new_inputs[name]), (node_id, name, original, new_inputs[name])
+        for key in ('output', 'output_name', 'output_is_list', 'is_input_list', 'output_node', 'category', 'display_name'):
+            assert old[key] == new[key], (node_id, key, old[key], new[key])
+        # Standard context lives in cls.hidden; orchestrator metadata remains
+        # accepted by its original kwarg name, without creating new widgets.
+        signature = inspect.signature(cls.execute)
+        for name, field in old['input'].get('hidden', {}).items():
+            if isinstance(field, list):
+                assert cls.GET_SCHEMA().accept_all_inputs, node_id
+                assert name in signature.parameters, (node_id, name)
+                assert signature.parameters[name].default == field[1]['default'], (node_id, name)
+            else:
+                assert name in new['input']['hidden'], (node_id, name)
+        expected_hidden = []
+        if node_id == 'DistributedModelName':
+            expected_hidden.extend(['unique_id', 'extra_pnginfo'])
+        if old['output_node']:
+            expected_hidden.extend(name for name in ['prompt', 'extra_pnginfo'] if name not in expected_hidden)
+        assert list(new['input'].get('hidden', {})) == expected_hidden, (node_id, new['input'].get('hidden'))
+    print('SCHEMA_PARITY_OK', len(mapping))
+    check_saved_workflows(mapping)
+    await check_execution(mapping, module, prompt_server, asset_manager)
+    print('V3_ACCEPTANCE_OK')
+
+
+asyncio.run(main())
@@ -0,0 +1,91 @@
+import importlib.util
+import sys
+import types
+import unittest
+from pathlib import Path
+
+
+class _PromptQueue:
+    def __init__(self):
+        self.items = []
+
+    def put(self, item):
+        self.items.append(item)
+
+
+def _load_async_helpers_module():
+    module_path = Path(__file__).resolve().parents[1] / "utils" / "async_helpers.py"
+    package_name = "dist_async_helpers_testpkg"
+
+    for mod_name in list(sys.modules):
+        if mod_name == package_name or mod_name.startswith(f"{package_name}."):
+            del sys.modules[mod_name]
+
+    root_pkg = types.ModuleType(package_name)
+    root_pkg.__path__ = []
+    sys.modules[package_name] = root_pkg
+
+    utils_pkg = types.ModuleType(f"{package_name}.utils")
+    utils_pkg.__path__ = []
+    sys.modules[f"{package_name}.utils"] = utils_pkg
+
+    execution_module = types.ModuleType("execution")
+
+    async def _validate_prompt(prompt_id, prompt, partial_execution_targets):
+        return (True, None, ["9"], {})
+
+    execution_module.validate_prompt = _validate_prompt
+    execution_module.SENSITIVE_EXTRA_DATA_KEYS = []
+    sys.modules["execution"] = execution_module
+
+    prompt_server = types.SimpleNamespace(
+        trigger_on_prompt=lambda payload: payload,
+        number=12,
+        prompt_queue=_PromptQueue(),
+    )
+    server_module = types.ModuleType("server")
+    server_module.PromptServer = types.SimpleNamespace(instance=prompt_server)
+    sys.modules["server"] = server_module
+
+    network_module = types.ModuleType(f"{package_name}.utils.network")
+    network_module.get_server_loop = lambda: None
+    sys.modules[f"{package_name}.utils.network"] = network_module
+
+    spec = importlib.util.spec_from_file_location(f"{package_name}.utils.async_helpers", module_path)
+    module = importlib.util.module_from_spec(spec)
+    assert spec is not None and spec.loader is not None
+    spec.loader.exec_module(module)
+    return module, prompt_server
+
+
+async_helpers, prompt_server = _load_async_helpers_module()
+
+
+class QueuePromptPayloadTests(unittest.IsolatedAsyncioTestCase):
+    async def test_queue_prompt_payload_includes_create_time_and_client_metadata(self):
+        result = await async_helpers.queue_prompt_payload(
+            {"1": {"class_type": "Node"}},
+            workflow_meta={"id": "workflow-1"},
+            client_id="client-1",
+            include_queue_metadata=True,
+        )
+
+        self.assertIsInstance(result["prompt_id"], str)
+        self.assertTrue(result["prompt_id"])
+        self.assertEqual(result["number"], 12)
+        self.assertEqual(result["node_errors"], {})
+
+        self.assertEqual(prompt_server.number, 13)
+        self.assertEqual(len(prompt_server.prompt_queue.items), 1)
+        queued_item = prompt_server.prompt_queue.items[0]
+        self.assertEqual(queued_item[0], 12)
+        extra_data = queued_item[3]
+        self.assertEqual(extra_data["client_id"], "client-1")
+        self.assertIn("create_time", extra_data)
+        self.assertIsInstance(extra_data["create_time"], int)
+        self.assertGreater(extra_data["create_time"], 0)
+        self.assertEqual(extra_data["extra_pnginfo"]["workflow"], {"id": "workflow-1"})
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,630 @@
+import importlib.util
+import sys
+import types
+import asyncio
+from pathlib import Path
+
+import torch
+
+
+def _register_real_transfer_codec(package_name, utils_pkg):
+    """Load the real utils/transfer_codec.py into the synthetic test package."""
+    codec_path = Path(__file__).resolve().parents[1] / "utils" / "transfer_codec.py"
+    codec_spec = importlib.util.spec_from_file_location(f"{package_name}.utils.transfer_codec", codec_path)
+    codec_module = importlib.util.module_from_spec(codec_spec)
+    sys.modules[f"{package_name}.utils.transfer_codec"] = codec_module
+    codec_spec.loader.exec_module(codec_module)
+    utils_pkg.transfer_codec = codec_module
+    return codec_module
+
+
+def _load_collector_module():
+    module_path = Path(__file__).resolve().parents[1] / "nodes" / "collector.py"
+    package_name = "dist_collector_list_testpkg"
+
+    for mod_name in list(sys.modules):
+        if mod_name == package_name or mod_name.startswith(f"{package_name}."):
+            del sys.modules[mod_name]
+
+    root_pkg = types.ModuleType(package_name)
+    root_pkg.__path__ = []
+    sys.modules[package_name] = root_pkg
+
+    nodes_pkg = types.ModuleType(f"{package_name}.nodes")
+    nodes_pkg.__path__ = []
+    sys.modules[f"{package_name}.nodes"] = nodes_pkg
+
+    utils_pkg = types.ModuleType(f"{package_name}.utils")
+    utils_pkg.__path__ = []
+    sys.modules[f"{package_name}.utils"] = utils_pkg
+    _register_real_transfer_codec(package_name, utils_pkg)
+
+    class _Routes:
+        def post(self, _path):
+            return lambda fn: fn
+
+        def get(self, _path):
+            return lambda fn: fn
+
+    prompt_server = types.SimpleNamespace(
+        routes=_Routes(),
+        distributed_jobs_lock=None,
+        distributed_pending_jobs={},
+    )
+    server_module = types.ModuleType("server")
+    server_module.PromptServer = types.SimpleNamespace(instance=prompt_server)
+    sys.modules["server"] = server_module
+
+    comfy_module = types.ModuleType("comfy")
+    model_management = types.ModuleType("comfy.model_management")
+
+    class InterruptProcessingException(Exception):
+        pass
+
+    model_management.InterruptProcessingException = InterruptProcessingException
+    model_management.throw_exception_if_processing_interrupted = lambda: None
+    comfy_module.model_management = model_management
+
+    comfy_utils = types.ModuleType("comfy.utils")
+
+    class ProgressBar:
+        def __init__(self, _total):
+            self.total = _total
+            self.updates = []
+
+        def update(self, value):
+            self.updates.append(value)
+
+    comfy_utils.ProgressBar = ProgressBar
+    comfy_module.utils = comfy_utils
+    sys.modules["comfy"] = comfy_module
+    sys.modules["comfy.model_management"] = model_management
+    sys.modules["comfy.utils"] = comfy_utils
+
+    aiohttp_module = types.ModuleType("aiohttp")
+    aiohttp_module.ClientTimeout = lambda total: types.SimpleNamespace(total=total)
+    sys.modules["aiohttp"] = aiohttp_module
+
+    logging_module = types.ModuleType(f"{package_name}.utils.logging")
+    logging_module.debug_log = lambda *_args, **_kwargs: None
+    logging_module.log = lambda *_args, **_kwargs: None
+    sys.modules[f"{package_name}.utils.logging"] = logging_module
+
+    config_module = types.ModuleType(f"{package_name}.utils.config")
+    config_module.get_worker_timeout_seconds = lambda: 0.1
+    config_module.load_config = lambda: {"workers": []}
+    config_module.is_master_delegate_only = lambda: False
+    sys.modules[f"{package_name}.utils.config"] = config_module
+
+    constants_module = types.ModuleType(f"{package_name}.utils.constants")
+    constants_module.HEARTBEAT_INTERVAL = 1.0
+    constants_module.TRANSFER_MAX_CHUNK_BYTES = 32 * 1024 * 1024
+    constants_module.TRANSFER_MAX_REQUEST_BYTES = 96 * 1024 * 1024
+    sys.modules[f"{package_name}.utils.constants"] = constants_module
+
+    image_module = types.ModuleType(f"{package_name}.utils.image")
+    def _ensure_contiguous(tensor):
+        return tensor.contiguous() if hasattr(tensor, "contiguous") else tensor
+
+    image_module.ensure_contiguous = _ensure_contiguous
+    image_module.tensor_to_pil = lambda *_args, **_kwargs: None
+    image_module.pil_to_tensor = lambda value: value
+    sys.modules[f"{package_name}.utils.image"] = image_module
+
+    network_module = types.ModuleType(f"{package_name}.utils.network")
+    network_module.build_worker_url = lambda worker: "http://worker"
+    network_module.get_client_session = lambda: None
+    network_module.probe_worker = lambda *_args, **_kwargs: None
+    sys.modules[f"{package_name}.utils.network"] = network_module
+
+    audio_payload_module = types.ModuleType(f"{package_name}.utils.audio_payload")
+    audio_payload_module.encode_audio_payload = lambda audio: audio
+    sys.modules[f"{package_name}.utils.audio_payload"] = audio_payload_module
+
+    async_helpers_module = types.ModuleType(f"{package_name}.utils.async_helpers")
+    async_helpers_module.run_async_in_server_loop = lambda coro: asyncio.run(coro)
+    sys.modules[f"{package_name}.utils.async_helpers"] = async_helpers_module
+
+    spec = importlib.util.spec_from_file_location(f"{package_name}.nodes.collector", module_path)
+    module = importlib.util.module_from_spec(spec)
+    assert spec is not None and spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_collector_opts_into_comfyui_list_inputs():
+    collector = _load_collector_module().DistributedCollectorNode
+
+    assert collector.INPUT_IS_LIST is True
+
+
+def test_collector_exposes_images_as_optional_input():
+    input_types = _load_collector_module().DistributedCollectorNode.INPUT_TYPES()
+
+    assert "images" not in input_types["required"]
+    assert input_types["optional"]["images"] == ("IMAGE",)
+
+
+def test_audio_only_pass_through_returns_no_images_and_preserves_audio():
+    collector = _load_collector_module().DistributedCollectorNode()
+    audio = {"waveform": torch.ones(1, 2, 4), "sample_rate": 48000}
+
+    images, returned_audio = collector.run(images=None, audio=[audio])
+
+    assert images is None
+    assert returned_audio is audio
+
+
+def test_collector_rejects_missing_images_and_audio():
+    collector = _load_collector_module().DistributedCollectorNode()
+
+    try:
+        collector.run(images=None, audio=None)
+    except ValueError as exc:
+        assert "image or audio" in str(exc).lower()
+    else:
+        raise AssertionError("Expected collector to reject a run with no media input")
+
+
+def test_delegate_only_master_allows_no_local_media_input():
+    collector = _load_collector_module().DistributedCollectorNode()
+
+    images, audio = collector.run(
+        images=None,
+        audio=None,
+        multi_job_id=["delegate-audio-job"],
+        delegate_only=[True],
+        enabled_worker_ids=["[]"],
+    )
+
+    assert images is None
+    assert tuple(audio["waveform"].shape) == (1, 2, 1)
+
+
+def test_pass_through_collapses_comfyui_image_list_to_batch_and_unwraps_hidden_inputs():
+    collector = _load_collector_module().DistributedCollectorNode()
+    first = torch.zeros(1, 2, 2, 3)
+    second = torch.ones(1, 2, 2, 3)
+
+    images, audio = collector.run(
+        images=[first, second],
+        load_balance=[False],
+        audio=[None],
+        multi_job_id=[""],
+        is_worker=[False],
+        master_url=[""],
+        enabled_worker_ids=["[]"],
+        worker_batch_size=[1],
+        worker_id=[""],
+        pass_through=[False],
+        delegate_only=[False],
+    )
+
+    assert tuple(images.shape) == (2, 2, 2, 3)
+    assert torch.equal(images[0:1], first)
+    assert torch.equal(images[1:2], second)
+    assert tuple(audio["waveform"].shape) == (1, 2, 1)
+
+
+def test_worker_list_input_sends_one_completion_sequence_with_last_only_on_final_item():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    first = torch.zeros(1, 2, 2, 3)
+    second = torch.ones(1, 2, 2, 3)
+    posted_payloads = []
+
+    class _FakeImage:
+        def save(self, fp, format=None, compress_level=None):
+            fp.write(b"png-bytes")
+
+    class _FakeResponse:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return False
+
+        def raise_for_status(self):
+            return None
+
+    class _FakeSession:
+        def post(self, url, json, timeout):
+            posted_payloads.append(json)
+            return _FakeResponse()
+
+    async def _fake_get_client_session():
+        return _FakeSession()
+
+    module.tensor_to_pil = lambda *_args, **_kwargs: _FakeImage()
+    module.get_client_session = _fake_get_client_session
+    module.encode_audio_payload = lambda _audio: None
+
+    images, audio = collector.run(
+        images=[first, second],
+        load_balance=[False],
+        audio=[None],
+        multi_job_id=["job-list-1"],
+        is_worker=[True],
+        master_url=["http://master"],
+        enabled_worker_ids=["[]"],
+        worker_batch_size=[1],
+        worker_id=["worker-a"],
+        pass_through=[False],
+        delegate_only=[False],
+    )
+
+    assert tuple(images.shape) == (2, 2, 2, 3)
+    assert tuple(audio["waveform"].shape) == (1, 2, 1)
+    assert len(posted_payloads) == 2
+    assert [payload["batch_idx"] for payload in posted_payloads] == [0, 1]
+    assert [payload["is_last"] for payload in posted_payloads] == [False, True]
+    assert {payload["job_id"] for payload in posted_payloads} == {"job-list-1"}
+    assert {payload["worker_id"] for payload in posted_payloads} == {"worker-a"}
+
+
+def test_audio_only_worker_sends_one_completion_without_image():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    audio = {"waveform": torch.ones(1, 2, 4), "sample_rate": 48000}
+    posted = []
+
+    class _FakeResponse:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return False
+
+        def raise_for_status(self):
+            return None
+
+    class _FakeSession:
+        def post(self, url, json, timeout):
+            posted.append((url, json, timeout.total))
+            return _FakeResponse()
+
+    async def _fake_get_client_session():
+        return _FakeSession()
+
+    module.get_client_session = _fake_get_client_session
+    module.encode_audio_payload = lambda value: {"encoded": value is audio}
+
+    images, returned_audio = collector.run(
+        images=None,
+        audio=[audio],
+        multi_job_id=["audio-job"],
+        is_worker=[True],
+        master_url=["http://master"],
+        worker_id=["worker-a"],
+    )
+
+    assert images is None
+    assert returned_audio is audio
+    assert len(posted) == 1
+    assert posted[0][0] == "http://master/distributed/job_complete"
+    assert posted[0][2] == 600
+    assert posted[0][1] == {
+        "job_id": "audio-job",
+        "worker_id": "worker-a",
+        "batch_idx": 0,
+        "audio": {"encoded": True},
+        "is_last": True,
+    }
+
+
+def test_audio_only_master_combines_local_and_worker_audio():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    master_audio = {"waveform": torch.ones(1, 2, 2), "sample_rate": 48000}
+    worker_audio = {"waveform": torch.full((1, 2, 3), 2.0), "sample_rate": 48000}
+    module.prompt_server.distributed_jobs_lock = asyncio.Lock()
+    queue = asyncio.Queue()
+    queue.put_nowait(
+        {
+            "worker_id": "worker-a",
+            "image_index": 0,
+            "tensor": None,
+            "audio": worker_audio,
+            "is_last": True,
+        }
+    )
+    module.prompt_server.distributed_pending_jobs = {"audio-job": queue}
+
+    images, combined_audio = asyncio.run(
+        collector.execute(
+            images=None,
+            audio=master_audio,
+            multi_job_id="audio-job",
+            enabled_worker_ids='["worker-a"]',
+        )
+    )
+
+    assert images is None
+    assert combined_audio["sample_rate"] == 48000
+    assert tuple(combined_audio["waveform"].shape) == (1, 2, 5)
+    assert torch.equal(combined_audio["waveform"][..., :2], master_audio["waveform"])
+    assert torch.equal(combined_audio["waveform"][..., 2:], worker_audio["waveform"])
+
+
+def test_delegate_only_audio_collects_worker_audio_without_placeholder_image():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    worker_audio = {"waveform": torch.full((1, 2, 3), 2.0), "sample_rate": 48000}
+    module.prompt_server.distributed_jobs_lock = asyncio.Lock()
+    queue = asyncio.Queue()
+    queue.put_nowait(
+        {
+            "worker_id": "worker-a",
+            "image_index": 0,
+            "tensor": None,
+            "audio": worker_audio,
+            "is_last": True,
+        }
+    )
+    module.prompt_server.distributed_pending_jobs = {"delegate-audio-job": queue}
+
+    images, combined_audio = asyncio.run(
+        collector.execute(
+            images=None,
+            audio=None,
+            multi_job_id="delegate-audio-job",
+            enabled_worker_ids='["worker-a"]',
+            delegate_only=True,
+        )
+    )
+
+    assert images is None
+    assert combined_audio["sample_rate"] == 48000
+    assert torch.equal(combined_audio["waveform"], worker_audio["waveform"])
+
+
+# --------------------------------------------------------------------------- #
+# Compressed worker -> master transfer
+# --------------------------------------------------------------------------- #
+
+class _RecordingResponse:
+    def __init__(self, status=200, text=""):
+        self.status = status
+        self._text = text
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return False
+
+    async def text(self):
+        return self._text
+
+    def raise_for_status(self):
+        if self.status >= 400:
+            raise RuntimeError(f"HTTP {self.status}")
+
+
+class _RecordingSession:
+    def __init__(self, statuses=None, text="Invalid JSON payload"):
+        self.calls = []
+        self._statuses = list(statuses or [])
+        self._text = text
+
+    def post(self, url, timeout, json=None, data=None):
+        self.calls.append({"url": url, "json": json, "data": data, "timeout": timeout.total})
+        status = self._statuses.pop(0) if self._statuses else 200
+        return _RecordingResponse(status=status, text=self._text)
+
+
+def _install_fake_transport(module, session):
+    async def _fake_get_client_session():
+        return session
+
+    module.get_client_session = _fake_get_client_session
+    # Record the multipart content instead of building a real aiohttp.FormData.
+    module.DistributedCollectorNode._build_multipart = staticmethod(
+        lambda envelope, parts: {"envelope": envelope, "parts": list(parts)}
+    )
+
+
+def _run_worker(collector, images, audio=None, **kwargs):
+    return collector.run(
+        images=[images],
+        audio=[audio],
+        multi_job_id=["job-c"],
+        is_worker=[True],
+        master_url=["http://master"],
+        worker_id=["worker-a"],
+        **{key: [value] for key, value in kwargs.items()},
+    )
+
+
+def test_collector_exposes_transfer_widgets_with_legacy_default():
+    module = _load_collector_module()
+    optional = module.DistributedCollectorNode.INPUT_TYPES()["optional"]
+
+    formats, options = optional["transfer_format"]
+    assert "legacy_png" in formats and "h264" in formats and "ffv1" in formats
+    assert options["default"] == "legacy_png"
+    assert optional["transfer_quality"][0] == "INT"
+
+
+def test_worker_sends_video_batch_as_one_multipart_chunk_with_audio_on_last():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    module.encode_audio_payload = lambda value: None if value is None else {"encoded": True}
+    images = torch.rand(6, 32, 48, 3)
+
+    _run_worker(
+        collector,
+        images,
+        audio={"waveform": torch.ones(1, 2, 4), "sample_rate": 48000},
+        transfer_format="ffv1",
+        transfer_quality=90,
+    )
+
+    assert len(session.calls) == 1
+    call = session.calls[0]
+    assert call["url"] == "http://master/distributed/job_complete"
+    assert call["json"] is None
+    envelope = call["data"]["envelope"]
+    assert envelope["format"] == "ffv1"
+    assert (envelope["start_index"], envelope["count"]) == (0, 6)
+    assert (envelope["width"], envelope["height"]) == (48, 32)
+    assert envelope["is_last"] is True
+    assert envelope["audio"] == {"encoded": True}
+    assert envelope["job_id"] == "job-c" and envelope["worker_id"] == "worker-a"
+    assert len(call["data"]["parts"]) == 1
+
+
+def test_worker_marks_only_final_chunk_as_last():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    module.TRANSFER_MAX_CHUNK_BYTES = 1  # force one frame per request
+
+    _run_worker(collector, torch.rand(3, 8, 8, 3), transfer_format="png")
+
+    envelopes = [call["data"]["envelope"] for call in session.calls]
+    assert [(e["start_index"], e["count"], e["is_last"]) for e in envelopes] == [
+        (0, 1, False),
+        (1, 1, False),
+        (2, 1, True),
+    ]
+    assert "audio" not in envelopes[-1]
+
+
+def test_worker_falls_back_to_legacy_png_when_master_rejects_multipart():
+    from PIL import Image
+    import numpy as np
+
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession(statuses=[400])
+    _install_fake_transport(module, session)
+    module.tensor_to_pil = lambda tensor, idx: Image.fromarray(
+        (255 * tensor[idx].cpu().numpy()).astype(np.uint8)
+    )
+
+    _run_worker(collector, torch.rand(2, 8, 8, 3), transfer_format="h264")
+
+    assert session.calls[0]["data"] is not None  # compressed attempt
+    legacy = [call["json"] for call in session.calls[1:]]
+    assert [payload["batch_idx"] for payload in legacy] == [0, 1]
+    assert all(payload["image"].startswith("data:image/png;base64,") for payload in legacy)
+    assert [payload["is_last"] for payload in legacy] == [False, True]
+
+
+def test_worker_uses_legacy_path_for_unknown_transfer_format():
+    from PIL import Image
+    import numpy as np
+
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    module.tensor_to_pil = lambda tensor, idx: Image.fromarray(
+        (255 * tensor[idx].cpu().numpy()).astype(np.uint8)
+    )
+
+    _run_worker(collector, torch.rand(1, 8, 8, 3), transfer_format="gif")
+
+    assert len(session.calls) == 1
+    assert session.calls[0]["json"]["image"].startswith("data:image/png;base64,")
+
+
+def test_worker_falls_back_when_video_encoder_missing():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    codec = module.transfer_codec
+    original = codec.video_codec_available
+    codec.video_codec_available = lambda fmt: fmt == "h264" and original("h264")
+    try:
+        _run_worker(collector, torch.rand(2, 16, 16, 3), transfer_format="av1")
+    finally:
+        codec.video_codec_available = original
+
+    assert session.calls[0]["data"]["envelope"]["format"] == "h264"
+
+
+def test_worker_does_not_fall_back_on_non_legacy_rejection():
+    import pytest
+
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession(statuses=[400], text="Invalid multipart payload: Request Entity Too Large")
+    _install_fake_transport(module, session)
+
+    with pytest.raises(RuntimeError, match="MAX_REQUEST_BYTES"):
+        _run_worker(collector, torch.rand(2, 8, 8, 3), transfer_format="png")
+
+    # One compressed attempt, no legacy resend of the batch.
+    assert len(session.calls) == 1
+    assert session.calls[0]["json"] is None
+
+
+def test_worker_sends_nothing_when_a_frame_cannot_fit():
+    import numpy as np
+    import pytest
+
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    reserve = module.DistributedCollectorNode.TRANSFER_ENVELOPE_RESERVE_BYTES
+    module.TRANSFER_MAX_REQUEST_BYTES = reserve + 32 * 1024
+    module.TRANSFER_MAX_CHUNK_BYTES = 32 * 1024
+    # Frame 0 is tiny; frame 2 is noise that cannot fit in 32 KiB as PNG.
+    images = torch.zeros(3, 128, 128, 3)
+    images[2] = torch.from_numpy(np.random.default_rng(1).random((128, 128, 3), dtype=np.float32))
+
+    with pytest.raises(module.transfer_codec.FrameTooLargeError):
+        _run_worker(collector, images, transfer_format="png")
+
+    assert session.calls == []
+
+
+def test_worker_sends_audio_separately_when_it_would_overflow_last_request():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    reserve = module.DistributedCollectorNode.TRANSFER_ENVELOPE_RESERVE_BYTES
+    module.TRANSFER_MAX_REQUEST_BYTES = reserve + 64 * 1024
+    module.TRANSFER_MAX_CHUNK_BYTES = 64 * 1024
+    module.encode_audio_payload = lambda value: None if value is None else {"data": "x" * (128 * 1024)}
+
+    _run_worker(
+        collector,
+        torch.zeros(2, 16, 16, 3),
+        audio={"waveform": torch.ones(1, 2, 4), "sample_rate": 48000},
+        transfer_format="png",
+    )
+
+    multipart = [call["data"]["envelope"] for call in session.calls if call["data"] is not None]
+    assert [e["is_last"] for e in multipart] == [False]
+    assert all("audio" not in e for e in multipart)
+    final = session.calls[-1]["json"]
+    assert final["is_last"] is True and final["audio"]["data"].startswith("x")
+    assert "image" not in final
+
+
+def test_worker_attaches_audio_to_last_chunk_when_it_fits():
+    module = _load_collector_module()
+    collector = module.DistributedCollectorNode()
+    session = _RecordingSession()
+    _install_fake_transport(module, session)
+    module.encode_audio_payload = lambda value: None if value is None else {"data": "small"}
+
+    _run_worker(
+        collector,
+        torch.zeros(2, 16, 16, 3),
+        audio={"waveform": torch.ones(1, 2, 4), "sample_rate": 48000},
+        transfer_format="png",
+    )
+
+    assert len(session.calls) == 1
+    envelope = session.calls[0]["data"]["envelope"]
+    assert envelope["is_last"] is True and envelope["audio"] == {"data": "small"}
@@ -90,14 +90,48 @@ class NetworkHelpersTests(unittest.TestCase):
            "https://master.example.com",
        )

+    def test_build_master_url_ignores_stale_saved_port_and_uses_runtime_port(self):
+        cfg = {"master": {"host": "192.168.68.56", "port": 8001}}
+        prompt_server = types.SimpleNamespace(address="127.0.0.1", port=8188)
+        self.assertEqual(
+            network.build_master_url(config=cfg, prompt_server_instance=prompt_server),
+            "http://192.168.68.56:8188",
+        )
+
+    def test_build_master_url_keeps_explicit_port_in_host(self):
+        cfg = {"master": {"host": "192.168.68.56:8001"}}
+        prompt_server = types.SimpleNamespace(address="127.0.0.1", port=8188)
+        self.assertEqual(
+            network.build_master_url(config=cfg, prompt_server_instance=prompt_server),
+            "http://192.168.68.56:8001",
+        )
+
    def test_build_master_url_falls_back_to_server_address(self):
-        cfg = {"master": {"host": ""}}
+        cfg = {"master": {"host": "", "port": 8001}}
        prompt_server = types.SimpleNamespace(address="0.0.0.0", port=8190)
        self.assertEqual(
            network.build_master_url(config=cfg, prompt_server_instance=prompt_server),
            "http://127.0.0.1:8190",
        )

+    def test_build_master_callback_url_uses_loopback_for_local_worker(self):
+        cfg = {"master": {"host": "192.168.68.56"}}
+        prompt_server = types.SimpleNamespace(address="127.0.0.1", port=8001)
+        worker = {"id": "w1", "type": "local", "host": "localhost", "port": 8189}
+        self.assertEqual(
+            network.build_master_callback_url(worker, config=cfg, prompt_server_instance=prompt_server),
+            "http://127.0.0.1:8001",
+        )
+
+    def test_build_master_callback_url_keeps_public_master_url_for_remote_worker(self):
+        cfg = {"master": {"host": "192.168.68.56"}}
+        prompt_server = types.SimpleNamespace(address="127.0.0.1", port=8001)
+        worker = {"id": "w2", "type": "remote", "host": "192.168.68.99", "port": 8189}
+        self.assertEqual(
+            network.build_master_callback_url(worker, config=cfg, prompt_server_instance=prompt_server),
+            "http://192.168.68.56:8001",
+        )
+

 if __name__ == "__main__":
    unittest.main()
@@ -86,27 +86,25 @@ class ParseTilesFromFormTests(unittest.TestCase):

    # --- happy paths ---

-    def test_single_tile_returns_one_entry(self):
+    def test_single_tile_returns_image_and_metadata(self):
        tiles = pp._parse_tiles_from_form(_make_form(1))
        self.assertEqual(len(tiles), 1)
-
-    def test_multiple_tiles_all_returned(self):
-        tiles = pp._parse_tiles_from_form(_make_form(3))
-        self.assertEqual(len(tiles), 3)
-
-    def test_tile_image_is_pil_image(self):
-        tiles = pp._parse_tiles_from_form(_make_form(1))
-        self.assertIsInstance(tiles[0]["image"], PILImage.Image)
-
-    def test_tile_metadata_fields_are_parsed(self):
-        tiles = pp._parse_tiles_from_form(_make_form(1))
        tile = tiles[0]
+        self.assertIsInstance(tile["image"], PILImage.Image)
        self.assertEqual(tile["tile_idx"], 0)
        self.assertEqual(tile["x"], 0)
        self.assertEqual(tile["y"], 0)
        self.assertEqual(tile["extracted_width"], 64)
        self.assertEqual(tile["extracted_height"], 64)

+    def test_multiple_tiles_preserve_count_order_and_coordinates(self):
+        tiles = pp._parse_tiles_from_form(_make_form(3))
+        self.assertEqual(len(tiles), 3)
+        for i, tile in enumerate(tiles):
+            self.assertEqual(tile["tile_idx"], i)
+        self.assertEqual(tiles[1]["x"], 64)
+        self.assertEqual(tiles[2]["x"], 128)
+
    def test_padding_is_parsed_from_form(self):
        tiles = pp._parse_tiles_from_form(_make_form(1, padding=16))
        self.assertEqual(tiles[0]["padding"], 16)
@@ -138,16 +136,6 @@ class ParseTilesFromFormTests(unittest.TestCase):
        self.assertNotIn("batch_idx", tiles[0])
        self.assertNotIn("global_idx", tiles[0])

-    def test_tile_indices_match_metadata_order(self):
-        tiles = pp._parse_tiles_from_form(_make_form(3))
-        for i, tile in enumerate(tiles):
-            self.assertEqual(tile["tile_idx"], i)
-
-    def test_x_coordinates_reflect_metadata(self):
-        tiles = pp._parse_tiles_from_form(_make_form(3))
-        self.assertEqual(tiles[1]["x"], 64)
-        self.assertEqual(tiles[2]["x"], 128)
-
    # --- error cases ---

    def test_missing_tiles_metadata_raises_value_error(self):
@@ -71,6 +71,15 @@ def _collector_only_prompt():
    }


+def _audio_only_prompt():
+    """1(Audio source) → 2(DistributedCollector) → 3(Audio sink)."""
+    return {
+        "1": {"class_type": "LoadAudio", "inputs": {}},
+        "2": {"class_type": "DistributedCollector", "inputs": {"audio": ["1", 0]}},
+        "3": {"class_type": "SaveAudio", "inputs": {"audio": ["2", 1]}},
+    }
+
+
 def _delegate_prompt():
    """1 → 2 → 3(DistributedCollector) → 4(SaveImage)"""
    return {
@@ -217,6 +226,35 @@ class PrunePromptForWorkerTests(unittest.TestCase):
        self.assertEqual(len(preview_nodes), 1)
        self.assertEqual(preview_nodes[0]["inputs"]["images"], ["4", 0])

+    def test_injects_preview_audio_for_audio_only_collector(self):
+        result = pt.prune_prompt_for_worker(_audio_only_prompt())
+        preview_nodes = [n for n in result.values() if n.get("class_type") == "PreviewAudio"]
+        self.assertEqual(len(preview_nodes), 1)
+        self.assertEqual(preview_nodes[0]["inputs"]["audio"], ["2", 1])
+        self.assertFalse(any(n.get("class_type") == "PreviewImage" for n in result.values()))
+
+    def test_prefers_image_preview_when_collector_has_images_and_audio(self):
+        prompt = _linear_prompt()
+        prompt["6"] = {"class_type": "LoadAudio", "inputs": {}}
+        prompt["4"]["inputs"]["audio"] = ["6", 0]
+        result = pt.prune_prompt_for_worker(prompt)
+        self.assertEqual(
+            len([n for n in result.values() if n.get("class_type") == "PreviewImage"]),
+            1,
+        )
+        self.assertFalse(any(n.get("class_type") == "PreviewAudio" for n in result.values()))
+
+    def test_preserves_image_preview_for_distributed_upscale(self):
+        prompt = {
+            "1": {"class_type": "LoadImage", "inputs": {}},
+            "2": {"class_type": "UltimateSDUpscaleDistributed", "inputs": {"upscaled_image": ["1", 0]}},
+            "3": {"class_type": "SaveImage", "inputs": {"images": ["2", 0]}},
+        }
+        result = pt.prune_prompt_for_worker(prompt)
+        preview_nodes = [n for n in result.values() if n.get("class_type") == "PreviewImage"]
+        self.assertEqual(len(preview_nodes), 1)
+        self.assertEqual(preview_nodes[0]["inputs"]["images"], ["2", 0])
+
    def test_no_preview_image_when_no_downstream(self):
        result = pt.prune_prompt_for_worker(_collector_only_prompt())
        preview_nodes = [n for n in result.values() if n.get("class_type") == "PreviewImage"]
@@ -242,7 +280,7 @@ class PrunePromptForWorkerTests(unittest.TestCase):
    def test_upscale_node_is_treated_as_distributed(self):
        prompt = {
            "1": {"class_type": "KSampler", "inputs": {}},
-            "2": {"class_type": "UltimateSDUpscaleDistributed", "inputs": {"image": ["1", 0]}},
+            "2": {"class_type": "UltimateSDUpscaleDistributed", "inputs": {"upscaled_image": ["1", 0]}},
            "3": {"class_type": "SaveImage", "inputs": {"images": ["2", 0]}},
        }
        result = pt.prune_prompt_for_worker(prompt)
@@ -264,8 +302,8 @@ class PrepareDelegateMasterPromptTests(unittest.TestCase):
        self.assertNotIn("1", result)
        self.assertNotIn("2", result)

-    def test_removes_dangling_upstream_refs(self):
-        """Collector must not retain dangling refs to pruned upstream nodes."""
+    def test_replaces_dangling_upstream_ref_with_one_empty_image_placeholder(self):
+        """Collector must point to exactly one valid placeholder after pruning."""
        prompt = _delegate_prompt()
        result = pt.prepare_delegate_master_prompt(prompt, ["3"])
        collector_inputs = result["3"].get("inputs", {})
@@ -276,26 +314,520 @@ class PrepareDelegateMasterPromptTests(unittest.TestCase):
        self.assertNotEqual(source_id, "2")
        self.assertIn(source_id, result)
        self.assertEqual(result[source_id].get("class_type"), "DistributedEmptyImage")
-
-    def test_injects_empty_image_placeholder(self):
-        prompt = _delegate_prompt()
-        result = pt.prepare_delegate_master_prompt(prompt, ["3"])
        empty_nodes = [(nid, n) for nid, n in result.items() if n.get("class_type") == "DistributedEmptyImage"]
        self.assertEqual(len(empty_nodes), 1)
        placeholder_id = empty_nodes[0][0]
        self.assertEqual(result["3"]["inputs"]["images"], [placeholder_id, 0])

+    def test_audio_only_collector_does_not_get_image_placeholder(self):
+        prompt = _audio_only_prompt()
+        result = pt.prepare_delegate_master_prompt(prompt, ["2"])
+        empty_nodes = [n for n in result.values() if n.get("class_type") == "DistributedEmptyImage"]
+        self.assertEqual(empty_nodes, [])
+        self.assertNotIn("images", result["2"].get("inputs", {}))
+        self.assertNotIn("audio", result["2"].get("inputs", {}))
+
    def test_one_placeholder_per_collector(self):
        """Two collectors → two placeholders."""
        prompt = {
-            "1": {"class_type": "DistributedCollector", "inputs": {}},
-            "2": {"class_type": "DistributedCollector", "inputs": {}},
+            "1": {"class_type": "DistributedCollector", "inputs": {"images": ["10", 0]}},
+            "2": {"class_type": "DistributedCollector", "inputs": {"images": ["11", 0]}},
            "3": {"class_type": "SaveImage", "inputs": {"images": ["1", 0]}},
+            "10": {"class_type": "LoadImage", "inputs": {}},
+            "11": {"class_type": "LoadImage", "inputs": {}},
        }
        result = pt.prepare_delegate_master_prompt(prompt, ["1", "2"])
        empty_nodes = [n for n in result.values() if n.get("class_type") == "DistributedEmptyImage"]
        self.assertEqual(len(empty_nodes), 2)

+    def test_preserves_primitive_string_for_downstream_required_input(self):
+        """Delegate-only master keeps primitive inputs needed by SaveImage."""
+        save_image = type(
+            "SaveImage",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "filename_prefix": ("STRING",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {"SaveImage": save_image}
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "15": {"class_type": "PrimitiveString", "inputs": {"value": "test/input_bug"}},
+                "9": {
+                    "class_type": "SaveImage",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "filename_prefix": ["15", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        self.assertIn("15", result)
+        self.assertEqual(result["15"], prompt["15"])
+        self.assertEqual(result["9"]["inputs"]["filename_prefix"], ["15", 0])
+
+    def test_preserves_load_image_for_switch_alternate_required_input(self):
+        """Delegate-only master keeps LoadImage inputs needed by switches."""
+        prompt = {
+            "848": {"class_type": "LoadImage", "inputs": {"image": "input_bug2_00003_.png"}},
+            "862": {"class_type": "VAEDecode", "inputs": {}},
+            "854": {"class_type": "DistributedCollector", "inputs": {"images": ["862", 0]}},
+            "850": {
+                "class_type": "ComfySwitchNode",
+                "inputs": {
+                    "on_false": ["848", 0],
+                    "on_true": ["854", 0],
+                },
+            },
+            "851": {"class_type": "PreviewImage", "inputs": {"images": ["850", 0]}},
+        }
+
+        result = pt.prepare_delegate_master_prompt(prompt, ["854"])
+
+        self.assertIn("848", result)
+        self.assertEqual(result["850"]["inputs"]["on_false"], ["848", 0])
+        self.assertEqual(result["850"]["inputs"]["on_true"], ["854", 0])
+        self.assertNotIn("862", result)
+
+    def test_preserves_registered_string_utility_subgraph_for_downstream_required_input(self):
+        """Delegate-only master keeps scalar utility chains used by SaveImage."""
+        string_concat = type(
+            "StringConcatenate",
+            (),
+            {
+                "RETURN_TYPES": ("STRING",),
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "string_a": ("STRING",),
+                            "string_b": ("STRING",),
+                        }
+                    }
+                ),
+            },
+        )
+        save_image = type(
+            "SaveImage",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "filename_prefix": ("STRING",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {
+            "SaveImage": save_image,
+            "StringConcatenate": string_concat,
+        }
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "15": {"class_type": "PrimitiveString", "inputs": {"value": "test"}},
+                "16": {"class_type": "PrimitiveString", "inputs": {"value": "input_bug3"}},
+                "17": {
+                    "class_type": "StringConcatenate",
+                    "inputs": {
+                        "string_a": ["15", 0],
+                        "string_b": ["16", 0],
+                    },
+                },
+                "9": {
+                    "class_type": "SaveImage",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "filename_prefix": ["17", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        self.assertIn("15", result)
+        self.assertIn("16", result)
+        self.assertIn("17", result)
+        self.assertEqual(result["9"]["inputs"]["filename_prefix"], ["17", 0])
+        self.assertEqual(result["17"]["inputs"]["string_a"], ["15", 0])
+        self.assertEqual(result["17"]["inputs"]["string_b"], ["16", 0])
+
+    def test_preserves_registered_multi_string_join_subgraph_for_downstream_required_input(self):
+        """Delegate-only master keeps multi-input scalar utility chains."""
+        join_string_multi = type(
+            "JoinStringMulti",
+            (),
+            {
+                "RETURN_TYPES": ("STRING",),
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {"string_1": ("STRING",)},
+                        "optional": {
+                            "string_2": ("STRING",),
+                            "string_3": ("STRING",),
+                        },
+                    }
+                ),
+            },
+        )
+        save_image = type(
+            "SaveImage",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "filename_prefix": ("STRING",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {
+            "JoinStringMulti": join_string_multi,
+            "SaveImage": save_image,
+        }
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "15": {"class_type": "PrimitiveString", "inputs": {"value": "test"}},
+                "16": {"class_type": "PrimitiveString", "inputs": {"value": "input"}},
+                "17": {"class_type": "PrimitiveString", "inputs": {"value": "bug4"}},
+                "18": {
+                    "class_type": "JoinStringMulti",
+                    "inputs": {
+                        "string_1": ["15", 0],
+                        "string_2": ["16", 0],
+                        "string_3": ["17", 0],
+                    },
+                },
+                "9": {
+                    "class_type": "SaveImage",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "filename_prefix": ["18", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        self.assertIn("15", result)
+        self.assertIn("16", result)
+        self.assertIn("17", result)
+        self.assertIn("18", result)
+        self.assertEqual(result["9"]["inputs"]["filename_prefix"], ["18", 0])
+
+    def test_does_not_preserve_scalar_utility_with_heavy_upstream_dependency(self):
+        """Scalar utility nodes are retained only when their full input branch is safe."""
+        string_concat = type(
+            "StringConcatenate",
+            (),
+            {
+                "RETURN_TYPES": ("STRING",),
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "string_a": ("STRING",),
+                            "string_b": ("STRING",),
+                        }
+                    }
+                ),
+            },
+        )
+        save_image = type(
+            "SaveImage",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "filename_prefix": ("STRING",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {
+            "SaveImage": save_image,
+            "StringConcatenate": string_concat,
+        }
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "15": {"class_type": "PrimitiveString", "inputs": {"value": "test"}},
+                "17": {
+                    "class_type": "StringConcatenate",
+                    "inputs": {
+                        "string_a": ["15", 0],
+                        "string_b": ["8", 0],
+                    },
+                },
+                "9": {
+                    "class_type": "SaveImage",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "filename_prefix": ["17", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        self.assertNotIn("8", result)
+        self.assertNotIn("17", result)
+        self.assertNotIn("filename_prefix", result["9"]["inputs"])
+
+    def test_does_not_preserve_scalar_output_for_non_scalar_downstream_input(self):
+        """Scalar outputs are retained only for scalar/config downstream inputs."""
+        string_provider = type("StringProvider", (), {"RETURN_TYPES": ("STRING",)})
+        image_consumer = type(
+            "ImageConsumer",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "mask": ("IMAGE",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {
+            "ImageConsumer": image_consumer,
+            "StringProvider": string_provider,
+        }
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "17": {"class_type": "StringProvider", "inputs": {}},
+                "9": {
+                    "class_type": "ImageConsumer",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "mask": ["17", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        self.assertNotIn("17", result)
+        self.assertNotIn("mask", result["9"]["inputs"])
+
+    def test_preserves_scalar_list_join_subgraph_for_downstream_required_input(self):
+        """Delegate-only master keeps list-shaped scalar config chains."""
+        create_list = type(
+            "CreateList",
+            (),
+            {
+                "RETURN_TYPES": ("LIST",),
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {"inputs.input0": ("STRING",)},
+                        "optional": {
+                            "inputs.input1": ("STRING",),
+                            "inputs.input2": ("STRING",),
+                        },
+                    }
+                ),
+            },
+        )
+        string_data_list_join = type(
+            "StringDataListJoin",
+            (),
+            {
+                "RETURN_TYPES": ("STRING",),
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "strings": ("LIST",),
+                            "delimiter": ("STRING",),
+                        }
+                    }
+                ),
+            },
+        )
+        save_image = type(
+            "SaveImage",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "filename_prefix": ("STRING",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {
+            "CreateList": create_list,
+            "SaveImage": save_image,
+            "StringDataListJoin": string_data_list_join,
+        }
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "15": {"class_type": "PrimitiveString", "inputs": {"value": "test"}},
+                "17": {"class_type": "PrimitiveString", "inputs": {"value": "input_bug"}},
+                "29": {"class_type": "PrimitiveString", "inputs": {"value": "new"}},
+                "28": {
+                    "class_type": "CreateList",
+                    "inputs": {
+                        "inputs.input0": ["15", 0],
+                        "inputs.input1": ["17", 0],
+                        "inputs.input2": ["29", 0],
+                    },
+                },
+                "32": {
+                    "class_type": "StringDataListJoin",
+                    "inputs": {
+                        "strings": ["28", 0],
+                        "delimiter": "/",
+                    },
+                },
+                "9": {
+                    "class_type": "SaveImage",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "filename_prefix": ["32", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        self.assertIn("15", result)
+        self.assertIn("17", result)
+        self.assertIn("28", result)
+        self.assertIn("29", result)
+        self.assertIn("32", result)
+        self.assertEqual(result["9"]["inputs"]["filename_prefix"], ["32", 0])
+        self.assertEqual(result["32"]["inputs"]["strings"], ["28", 0])
+        self.assertEqual(result["28"]["inputs"]["inputs.input0"], ["15", 0])
+        self.assertNotIn("8", result)
+
+    def test_preserves_builtin_create_list_string_data_list_join_subgraph(self):
+        """Delegate-only master handles ComfyUI 0.23 CreateList data-list output."""
+        string_data_list_join = type(
+            "StringDataListJoin",
+            (),
+            {
+                "RETURN_TYPES": ("STRING",),
+                "INPUT_IS_LIST": True,
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "strings": ("STRING", {"forceInput": True}),
+                            "sep": ("STRING", {"default": " "}),
+                        }
+                    }
+                ),
+            },
+        )
+        save_image = type(
+            "SaveImage",
+            (),
+            {
+                "INPUT_TYPES": classmethod(
+                    lambda cls: {
+                        "required": {
+                            "images": ("IMAGE",),
+                            "filename_prefix": ("STRING",),
+                        }
+                    }
+                )
+            },
+        )
+        previous_mappings = getattr(pt, "_DELEGATE_MASTER_NODE_CLASS_MAPPINGS", None)
+        pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = {
+            "Basic data handling: StringDataListJoin": string_data_list_join,
+            "SaveImage": save_image,
+        }
+        try:
+            prompt = {
+                "8": {"class_type": "KSampler", "inputs": {}},
+                "11": {"class_type": "DistributedCollector", "inputs": {"images": ["8", 0]}},
+                "15": {"class_type": "PrimitiveString", "inputs": {"value": "input_bug"}},
+                "17": {"class_type": "PrimitiveString", "inputs": {"value": "test"}},
+                "29": {"class_type": "PrimitiveString", "inputs": {"value": "new"}},
+                "28": {
+                    "class_type": "CreateList",
+                    "inputs": {
+                        "inputs.input0": ["17", 0],
+                        "inputs.input1": ["15", 0],
+                        "inputs.input2": ["29", 0],
+                    },
+                },
+                "32": {
+                    "class_type": "Basic data handling: StringDataListJoin",
+                    "inputs": {
+                        "strings": ["28", 0],
+                        "sep": "/",
+                    },
+                },
+                "9": {
+                    "class_type": "SaveImage",
+                    "inputs": {
+                        "images": ["11", 0],
+                        "filename_prefix": ["32", 0],
+                    },
+                },
+            }
+
+            result = pt.prepare_delegate_master_prompt(prompt, ["11"])
+        finally:
+            pt._DELEGATE_MASTER_NODE_CLASS_MAPPINGS = previous_mappings
+
+        for node_id in ("15", "17", "28", "29", "32"):
+            self.assertIn(node_id, result)
+        self.assertEqual(result["9"]["inputs"]["filename_prefix"], ["32", 0])
+        self.assertEqual(result["32"]["inputs"]["strings"], ["28", 0])
+        self.assertEqual(result["28"]["inputs"]["inputs.input0"], ["17", 0])
+        self.assertNotIn("8", result)
+
    def test_result_is_independent_copy(self):
        prompt = _delegate_prompt()
        result = pt.prepare_delegate_master_prompt(prompt, ["3"])
@@ -0,0 +1,219 @@
+import importlib.util
+import io
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+import torch
+from PIL import Image
+
+
+def _load_codec():
+    path = Path(__file__).resolve().parents[1] / "utils" / "transfer_codec.py"
+    spec = importlib.util.spec_from_file_location("dist_transfer_codec_test", path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["dist_transfer_codec_test"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+tc = _load_codec()
+
+
+def _smooth_frames(count=4, height=67, width=91):
+    """Smooth moving gradient, closer to generated content than random noise."""
+    yy, xx = np.mgrid[0:height, 0:width].astype(np.float32)
+    frames = []
+    for i in range(count):
+        r = 0.5 + 0.5 * np.sin((xx + 3 * i) / 13.0)
+        g = 0.5 + 0.5 * np.cos((yy - 2 * i) / 11.0)
+        b = (xx + yy + 5 * i) / (width + height + 5 * count)
+        frames.append(np.stack([r, g, b], axis=-1))
+    return torch.from_numpy(np.stack(frames)).float()
+
+
+def _legacy_master_tensor(frame_tensor):
+    """What the unmodified pipeline delivered: tensor_to_pil -> PNG -> pil_to_tensor."""
+    img = Image.fromarray((255 * frame_tensor.numpy()).astype(np.uint8))
+    buf = io.BytesIO()
+    img.save(buf, format="PNG", compress_level=0)
+    with Image.open(io.BytesIO(buf.getvalue())) as decoded:
+        return np.array(decoded.convert("RGB")).astype(np.float32) / 255.0
+
+
+def _round_trip(frames_u8, fmt, quality=90, max_chunk_bytes=10**9):
+    out = []
+    chunks = list(tc.encode_chunks(frames_u8, fmt, quality, max_chunk_bytes))
+    for chunk in chunks:
+        envelope = {k: v for k, v in chunk.items() if k != "parts"}
+        out.extend(tc.decode_chunk(envelope, chunk["parts"]))
+    return chunks, out
+
+
+def _psnr(a, b):
+    mse = np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2)
+    return float("inf") if mse == 0 else 10 * np.log10(255.0**2 / mse)
+
+
+@pytest.mark.parametrize("fmt", ["png", "ffv1"])
+def test_lossless_formats_reproduce_legacy_master_tensors_exactly(fmt):
+    images = _smooth_frames()
+    frames = tc.tensor_batch_to_uint8(images)
+    _, decoded = _round_trip(frames, fmt)
+
+    assert len(decoded) == images.shape[0]
+    for i, frame in enumerate(decoded):
+        got = tc.uint8_frame_to_tensor_array(frame)[0]
+        assert np.array_equal(got, _legacy_master_tensor(images[i]))
+
+
+@pytest.mark.parametrize("fmt", ["jpeg", "webp", "h264", "h265", "av1"])
+def test_lossy_formats_round_trip_odd_sizes_with_reasonable_quality(fmt):
+    if fmt in tc.VIDEO_FORMATS and not tc.video_codec_available(fmt):
+        pytest.skip(f"{fmt} encoder not available in this PyAV build")
+    frames = tc.tensor_batch_to_uint8(_smooth_frames())
+    _, decoded = _round_trip(frames, fmt, quality=90)
+
+    assert len(decoded) == frames.shape[0]
+    for i, frame in enumerate(decoded):
+        assert frame.shape == frames[i].shape
+        assert frame.dtype == np.uint8
+        assert _psnr(frame, frames[i]) > 30
+
+
+def test_h265_handles_frames_smaller_than_ctu():
+    if not tc.video_codec_available("h265"):
+        pytest.skip("h265 encoder not available")
+    frames = tc.tensor_batch_to_uint8(_smooth_frames(count=3, height=17, width=23))
+    _, decoded = _round_trip(frames, "h265")
+    assert [f.shape for f in decoded] == [(17, 23, 3)] * 3
+
+
+def test_image_formats_split_chunks_by_byte_cap_and_keep_order():
+    frames = tc.tensor_batch_to_uint8(_smooth_frames(count=5))
+    one = len(tc.encode_image_frame(frames[0], "png", 90))
+    chunks, decoded = _round_trip(frames, "png", max_chunk_bytes=one * 2 + 1)
+
+    assert len(chunks) >= 3
+    assert [c["start_index"] for c in chunks] == sorted(c["start_index"] for c in chunks)
+    assert sum(c["count"] for c in chunks) == 5
+    assert all(len(c["parts"]) == c["count"] for c in chunks)
+    assert np.array_equal(np.stack(decoded), frames)
+
+
+def test_video_formats_split_chunks_by_frame_cap(monkeypatch):
+    monkeypatch.setattr(tc, "MAX_VIDEO_CHUNK_FRAMES", 2)
+    frames = tc.tensor_batch_to_uint8(_smooth_frames(count=5))
+    chunks, decoded = _round_trip(frames, "ffv1")
+
+    assert [(c["start_index"], c["count"]) for c in chunks] == [(0, 2), (2, 2), (4, 1)]
+    assert all(len(c["parts"]) == 1 for c in chunks)
+    assert np.array_equal(np.stack(decoded), frames)
+
+
+def test_tensor_batch_to_uint8_clips_and_normalizes_channels():
+    rgba = torch.tensor([[[[1.5, -0.2, 0.5, 0.3]]]])
+    assert tc.tensor_batch_to_uint8(rgba).tolist() == [[[[255, 0, 127]]]]
+
+    gray = torch.full((1, 2, 2, 1), 0.5)
+    out = tc.tensor_batch_to_uint8(gray)
+    assert out.shape == (1, 2, 2, 3)
+    assert (out == 127).all()
+
+
+def test_quality_to_crf_mapping():
+    assert tc.quality_to_crf(100, 51) == 0
+    assert tc.quality_to_crf(90, 51) == 13
+    assert tc.quality_to_crf(80, 51) == 19
+    assert tc.quality_to_crf(90, 63) == 16
+    assert tc.quality_to_crf(1, 51) == 51
+    assert tc.quality_to_crf("bogus", 51) == tc.quality_to_crf(tc.DEFAULT_TRANSFER_QUALITY, 51)
+
+
+def test_normalize_format_rejects_unknown_values():
+    assert tc.normalize_format(" H264 ") == "h264"
+    assert tc.normalize_format(None) == tc.DEFAULT_TRANSFER_FORMAT
+    with pytest.raises(tc.TransferCodecError):
+        tc.normalize_format("gif")
+
+
+def test_decode_chunk_validates_envelope_against_payload():
+    frames = tc.tensor_batch_to_uint8(_smooth_frames(count=2))
+    chunk = next(tc.encode_chunks(frames, "png", 90, 10**9))
+    envelope = {k: v for k, v in chunk.items() if k != "parts"}
+
+    with pytest.raises(tc.TransferCodecError, match="image parts"):
+        tc.decode_chunk({**envelope, "count": 3}, chunk["parts"])
+    with pytest.raises(tc.TransferCodecError, match="expected"):
+        tc.decode_chunk({**envelope, "width": 10}, chunk["parts"])
+    with pytest.raises(tc.TransferCodecError, match="count"):
+        tc.decode_chunk({**envelope, "count": 0}, chunk["parts"])
+    with pytest.raises(tc.TransferCodecError):
+        tc.decode_chunk(envelope, [b"not an image", b"nope"])
+
+    video = next(tc.encode_chunks(frames, "ffv1", 90, 10**9))
+    video_env = {k: v for k, v in video.items() if k != "parts"}
+    with pytest.raises(tc.TransferCodecError, match="frames"):
+        tc.decode_chunk({**video_env, "count": 5}, video["parts"])
+
+
+def test_legacy_format_is_not_chunk_encoded():
+    frames = tc.tensor_batch_to_uint8(_smooth_frames(count=1))
+    with pytest.raises(tc.TransferCodecError):
+        list(tc.encode_chunks(frames, "legacy_png", 90, 10**9))
+
+
+# --------------------------------------------------------------------------- #
+# Size bounds on finalized payloads
+# --------------------------------------------------------------------------- #
+
+def _noise_frames(count=30, height=360, width=640, seed=97):
+    """High-entropy frames: worst case for every codec, and enough encoder
+    lookahead that pre-flush buffer sizes badly underestimate final sizes."""
+    return np.random.default_rng(seed).integers(0, 256, size=(count, height, width, 3), dtype=np.uint8)
+
+
+@pytest.mark.parametrize("fmt", ["h264", "ffv1"])
+def test_video_chunks_are_bounded_after_encoder_flush(fmt):
+    frames = _noise_frames()
+    limit = 1024 * 1024
+    # Sanity: one unconstrained encode of this batch is far above the limit,
+    # so the bound below is actually being enforced.
+    unbounded = next(tc.encode_chunks(frames, fmt, 90, 10**12))
+    assert len(unbounded["parts"][0]) > 3 * limit
+
+    chunks = list(tc.encode_chunks(frames, fmt, 90, limit))
+
+    assert all(len(c["parts"]) == 1 and len(c["parts"][0]) <= limit for c in chunks)
+    assert [c["start_index"] for c in chunks] == list(np.cumsum([0] + [c["count"] for c in chunks[:-1]]))
+    assert sum(c["count"] for c in chunks) == len(frames)
+    decoded = [f for c in chunks for f in tc.decode_chunk(c, c["parts"])]
+    assert len(decoded) == len(frames)
+    if fmt == "ffv1":
+        assert np.array_equal(np.stack(decoded), frames)
+
+
+def test_single_video_frame_may_exceed_chunk_target_up_to_frame_limit():
+    frames = _noise_frames(count=3)
+    one_frame = len(next(tc.encode_chunks(frames[:1], "ffv1", 90, 10**12))["parts"][0])
+
+    chunks = list(tc.encode_chunks(frames, "ffv1", 90, one_frame // 2, one_frame * 2))
+
+    assert [c["count"] for c in chunks] == [1, 1, 1]
+    assert all(one_frame // 2 < len(c["parts"][0]) <= one_frame * 2 for c in chunks)
+
+
+@pytest.mark.parametrize("fmt", ["ffv1", "h264", "png"])
+def test_frame_that_cannot_fit_alone_raises(fmt):
+    frames = _noise_frames(count=2)
+    with pytest.raises(tc.FrameTooLargeError, match="request limit"):
+        list(tc.encode_chunks(frames, fmt, 90, 64 * 1024, 64 * 1024))
+
+
+def test_still_chunks_are_bounded():
+    frames = _noise_frames(count=10)
+    limit = 1024 * 1024
+    chunks = list(tc.encode_chunks(frames, "jpeg", 90, limit))
+    assert all(sum(len(p) for p in c["parts"]) <= limit for c in chunks)
+    assert sum(c["count"] for c in chunks) == 10
@@ -0,0 +1,125 @@
+"""Registered V3 DistributedCollector: transfer options in the public schema and forwarded to the runtime.
+
+Runs without a ComfyUI checkout by loading nodes/v3.py against a recording
+stand-in for comfy_api's io module. tests/test_v3_migration.py covers the same
+boundary against the real framework when COMFYUI_SOURCE_ROOT is set.
+"""
+import importlib.util
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+PKG = "dist_v3_transfer_testpkg"
+
+
+class _Field:
+    def __init__(self, kind, id=None, **kwargs):
+        self.kind = kind
+        self.id = id
+        self.kwargs = kwargs
+
+
+def _io_type(kind):
+    return types.SimpleNamespace(
+        Input=lambda id, **kw: _Field(kind, id, **kw),
+        Output=lambda id=None, **kw: _Field(kind, id, **kw),
+    )
+
+
+def _fake_io():
+    io = types.ModuleType("io")
+
+    class ComfyNode:
+        pass
+
+    io.ComfyNode = ComfyNode
+    io.Schema = lambda **kw: types.SimpleNamespace(**kw)
+    io.NodeOutput = lambda *values, **kw: ("NodeOutput", values, kw)
+    io.NumberDisplay = types.SimpleNamespace(number="number")
+    io.Hidden = types.SimpleNamespace(unique_id="unique_id", extra_pnginfo="extra_pnginfo")
+    for name in ("Int", "Float", "String", "Boolean", "Combo", "Image", "Audio",
+                 "AnyType", "Model", "Conditioning", "Vae"):
+        setattr(io, name, _io_type(name))
+    return io
+
+
+@pytest.fixture
+def v3(monkeypatch):
+    calls = []
+
+    class CollectorRuntime:
+        def run(self, **kwargs):
+            calls.append(kwargs)
+            return (kwargs["images"], kwargs["audio"])
+
+    def module(name, **attrs):
+        mod = types.ModuleType(name)
+        mod.__dict__.update(attrs)
+        monkeypatch.setitem(sys.modules, name, mod)
+        return mod
+
+    for name in [n for n in sys.modules if n == PKG or n.startswith(PKG + ".")]:
+        monkeypatch.delitem(sys.modules, name)
+    module(PKG, __path__=[])
+    module(f"{PKG}.nodes", __path__=[])
+    module(f"{PKG}.utils", __path__=[])
+    module(f"{PKG}.nodes.utilities")
+    module(f"{PKG}.nodes.distributed_upscale", UltimateSDUpscaleDistributed=object)
+    module(f"{PKG}.nodes.collector", DistributedCollectorNode=CollectorRuntime)
+    module("comfy", __path__=[])
+    module("comfy.samplers", KSampler=types.SimpleNamespace(SAMPLERS=["euler"], SCHEDULERS=["normal"]))
+    module("comfy_api", __path__=[])
+    module("comfy_api.v0_0_2", io=_fake_io())
+
+    codec_spec = importlib.util.spec_from_file_location(f"{PKG}.utils.transfer_codec", ROOT / "utils" / "transfer_codec.py")
+    codec = importlib.util.module_from_spec(codec_spec)
+    monkeypatch.setitem(sys.modules, f"{PKG}.utils.transfer_codec", codec)
+    codec_spec.loader.exec_module(codec)
+
+    spec = importlib.util.spec_from_file_location(f"{PKG}.nodes.v3", ROOT / "nodes" / "v3.py")
+    mod = importlib.util.module_from_spec(spec)
+    monkeypatch.setitem(sys.modules, f"{PKG}.nodes.v3", mod)
+    spec.loader.exec_module(mod)
+    return mod, codec, calls
+
+
+def test_registered_collector_schema_exposes_optional_transfer_inputs(v3):
+    mod, codec, _ = v3
+    schema = mod.DistributedCollector.define_schema()
+    inputs = {field.id: field for field in schema.inputs}
+
+    assert [field.id for field in schema.inputs] == [
+        "load_balance", "images", "audio", "transfer_format", "transfer_quality"]
+    fmt = inputs["transfer_format"]
+    assert fmt.kind == "Combo"
+    assert fmt.kwargs["options"] == list(codec.TRANSFER_FORMATS)
+    assert fmt.kwargs["default"] == "legacy_png"
+    assert fmt.kwargs["optional"] is True
+    quality = inputs["transfer_quality"]
+    assert quality.kind == "Int"
+    assert (quality.kwargs["default"], quality.kwargs["min"], quality.kwargs["max"]) == (90, 1, 100)
+    assert quality.kwargs["optional"] is True
+    assert schema.is_input_list is True
+
+
+def test_registered_collector_forwards_transfer_options(v3):
+    mod, _, calls = v3
+
+    mod.DistributedCollector.execute(images=["img"], audio=[None], transfer_format=["av1"], transfer_quality=[70],
+                                     multi_job_id=["job"], is_worker=[True])
+
+    assert calls[-1]["transfer_format"] == ["av1"]
+    assert calls[-1]["transfer_quality"] == [70]
+    assert calls[-1]["multi_job_id"] == ["job"]
+
+
+def test_registered_collector_defaults_to_legacy_transfer(v3):
+    mod, _, calls = v3
+
+    mod.DistributedCollector.execute(images=["img"])
+
+    assert calls[-1]["transfer_format"] == "legacy_png"
+    assert calls[-1]["transfer_quality"] == 90
@@ -0,0 +1,21 @@
+"""Real-framework acceptance; opt in with COMFYUI_SOURCE_ROOT."""
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+import pytest
+
+
+def test_native_v3_runtime():
+    comfy_root = os.environ.get('COMFYUI_SOURCE_ROOT')
+    if not comfy_root:
+        pytest.skip('Set COMFYUI_SOURCE_ROOT to run native ComfyUI V3 acceptance')
+    helper = Path(__file__).parent / 'helpers' / 'v3_runtime_check.py'
+    result = subprocess.run(
+        [sys.executable, str(helper), str(Path(comfy_root).resolve())],
+        capture_output=True, text=True, timeout=120,
+        env={**os.environ, 'COMFYUI_IS_WORKER': '1'},
+    )
+    assert result.returncode == 0, result.stdout + '\n' + result.stderr
+    assert 'V3_ACCEPTANCE_OK' in result.stdout
@@ -0,0 +1,113 @@
+import importlib.util
+import os
+import socket
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+def load_ports():
+    path = Path(__file__).resolve().parents[1] / "workers" / "ports.py"
+    spec = importlib.util.spec_from_file_location("worker_ports_test", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class WorkerPortTests(unittest.TestCase):
+    def setUp(self):
+        self.ports = load_ports()
+
+    def test_allocation_starts_above_actual_master_and_skips_assigned_and_occupied(self):
+        workers = [
+            {"id": "existing", "host": "localhost", "port": 8190, "enabled": False},
+            {"id": "remote", "host": "remote.example", "port": 8192},
+        ]
+        with patch.object(self.ports, "is_port_available", side_effect=lambda port: port != 8191):
+            self.assertEqual(self.ports.allocate_worker_ports(8189, workers, 3), [8192, 8193, 8194])
+
+    def test_local_host_forms_reserve_ports(self):
+        for host in ["::1", "[::1]", "http://localhost/", "HTTPS://LOCALHOST", "0.0.0.0", None]:
+            with self.subTest(host=host), patch.object(self.ports, "is_port_available", return_value=True):
+                self.assertEqual(self.ports.allocate_worker_ports(8189, [{"id": "local", "host": host, "port": 8190}], 1), [8191])
+
+    def test_exhaustion_is_explicit_not_a_partial_allocation(self):
+        with patch.object(self.ports, "is_port_available", return_value=True):
+            with self.assertRaisesRegex(ValueError, "available.*ports"):
+                self.ports.allocate_worker_ports(65534, [], 2)
+
+    def test_launch_rejects_master_port_without_reassigning_configuration(self):
+        worker = {"id": "manual", "port": 8189}
+        with self.assertRaisesRegex(ValueError, "master.*8189"):
+            self.ports.validate_worker_port(worker, 8189, [])
+        self.assertEqual(worker["port"], 8189)
+
+    def test_launch_rejects_another_local_workers_reserved_port(self):
+        worker = {"id": "manual", "port": 8190}
+        other = {"id": "other", "host": None, "port": 8190, "enabled": False}
+        with self.assertRaisesRegex(ValueError, "other"):
+            self.ports.validate_worker_port(worker, 8189, [worker, other])
+
+    def test_launch_ignores_itself_and_remote_workers_with_same_port(self):
+        worker = {"id": "manual", "port": 8190}
+        other = {"id": "remote", "host": "example.com", "port": 8190}
+        with patch.object(self.ports, "is_port_available", return_value=True):
+            self.ports.validate_worker_port(worker, 8189, [worker, other])
+
+    def test_launch_rejects_an_occupied_port(self):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
+            listener.bind(("127.0.0.1", 0))
+            listener.listen()
+            port = listener.getsockname()[1]
+            self.assertFalse(self.ports.is_port_available(port))
+            with self.assertRaisesRegex(ValueError, "already in use"):
+                self.ports.validate_worker_port({"id": "manual", "port": port}, 8189, [])
+
+    @unittest.skipIf(os.name == "nt", "asyncio does not reuse addresses on Windows")
+    def test_recently_closed_connection_does_not_block_worker_restart(self):
+        with socket.socket() as listener:
+            listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            listener.bind(("127.0.0.1", 0))
+            listener.listen(1)
+            port = listener.getsockname()[1]
+            with socket.create_connection(("127.0.0.1", port), timeout=2) as client:
+                accepted, _ = listener.accept()
+                with accepted:
+                    accepted.settimeout(2)
+                    accepted.shutdown(socket.SHUT_WR)
+                    self.assertEqual(client.recv(1), b"")
+                    client.shutdown(socket.SHUT_WR)
+                    self.assertEqual(accepted.recv(1), b"")
+        self.assertTrue(self.ports.is_port_available(port))
+        self.ports.validate_worker_port({"id": "restart", "port": port}, 1, [])
+        with socket.socket() as restarted:
+            restarted.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            restarted.bind(("127.0.0.1", port))
+            restarted.listen(1)
+
+    def test_active_listener_with_reuseaddr_is_still_a_conflict(self):
+        with socket.socket() as listener:
+            listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            listener.bind(("127.0.0.1", 0))
+            listener.listen(1)
+            self.assertFalse(self.ports.is_port_available(listener.getsockname()[1]))
+
+    @unittest.skipUnless(socket.has_ipv6, "IPv6 unavailable")
+    def test_ipv6_only_listener_is_still_a_conflict(self):
+        with socket.socket(socket.AF_INET6, socket.SOCK_STREAM) as listener:
+            listener.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
+            try:
+                listener.bind(("::1", 0))
+            except OSError as exc:
+                self.skipTest(f"IPv6 loopback unavailable: {exc}")
+            listener.listen(1)
+            self.assertFalse(self.ports.is_port_available(listener.getsockname()[1]))
+
+    def test_invalid_ports_fail_clearly(self):
+        for port in [0, 65536, "not-a-port", None, True, 8190.5]:
+            with self.subTest(port=port), self.assertRaisesRegex(ValueError, "port"):
+                self.ports.validate_worker_port({"id": "manual", "port": port}, 8189, [])
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,352 @@
+import importlib.util
+import os
+import sys
+import tempfile
+import types
+import unittest
+from argparse import Namespace
+from pathlib import Path
+from unittest.mock import patch
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import URL, make_url
+
+
+def _load_process_module(module_filename: str):
+    module_path = Path(__file__).resolve().parents[1] / "workers" / "process" / module_filename
+    package_name = "dist_proc_testpkg"
+    module_name = module_filename[:-3]
+
+    for mod_name in list(sys.modules):
+        if mod_name == package_name or mod_name.startswith(f"{package_name}."):
+            del sys.modules[mod_name]
+
+    root_pkg = types.ModuleType(package_name)
+    root_pkg.__path__ = []
+    sys.modules[package_name] = root_pkg
+
+    workers_pkg = types.ModuleType(f"{package_name}.workers")
+    workers_pkg.__path__ = [str(module_path.parents[1])]
+    sys.modules[f"{package_name}.workers"] = workers_pkg
+
+    process_pkg = types.ModuleType(f"{package_name}.workers.process")
+    process_pkg.__path__ = []
+    sys.modules[f"{package_name}.workers.process"] = process_pkg
+
+    utils_pkg = types.ModuleType(f"{package_name}.utils")
+    utils_pkg.__path__ = []
+    sys.modules[f"{package_name}.utils"] = utils_pkg
+
+    logging_module = types.ModuleType(f"{package_name}.utils.logging")
+    logging_module.debug_log = lambda *_args, **_kwargs: None
+    logging_module.log = lambda *_args, **_kwargs: None
+    sys.modules[f"{package_name}.utils.logging"] = logging_module
+
+    process_module = types.ModuleType(f"{package_name}.utils.process")
+    process_module.get_python_executable = lambda: "/usr/bin/test-python"
+    process_module.is_process_alive = lambda _pid: False
+    process_module.terminate_process = lambda *_args, **_kwargs: None
+    sys.modules[f"{package_name}.utils.process"] = process_module
+
+    config_module = types.ModuleType(f"{package_name}.utils.config")
+    config_module.load_config = lambda: {"workers": [], "settings": {"stop_workers_on_master_exit": False}}
+    config_module.save_config = lambda _config: None
+    sys.modules[f"{package_name}.utils.config"] = config_module
+    constants_module = types.ModuleType(f"{package_name}.utils.constants")
+    constants_module.PROCESS_TERMINATION_TIMEOUT = 1
+    constants_module.PROCESS_WAIT_TIMEOUT = 1
+    constants_module.WORKER_CHECK_INTERVAL = 0.01
+    sys.modules[f"{package_name}.utils.constants"] = constants_module
+    network_module = types.ModuleType(f"{package_name}.utils.network")
+    network_module.get_server_port = lambda: 8189
+    sys.modules[f"{package_name}.utils.network"] = network_module
+
+    spec = importlib.util.spec_from_file_location(
+        f"{package_name}.workers.process.{module_name}",
+        module_path,
+    )
+    module = importlib.util.module_from_spec(spec)
+    assert spec is not None and spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+root_discovery_module = _load_process_module("root_discovery.py")
+launch_builder_module = _load_process_module("launch_builder.py")
+
+
+class ComfyRootDiscoveryTests(unittest.TestCase):
+    def test_prefers_loaded_comfyui_module_path(self):
+        discovery = root_discovery_module.ComfyRootDiscovery()
+        server_module = types.SimpleNamespace(__file__="/opt/ComfyUI/server.py")
+
+        def fake_exists(path):
+            return path == "/opt/ComfyUI/main.py"
+
+        with patch.dict(sys.modules, {"server": server_module}, clear=False), \
+             patch.object(root_discovery_module.os.path, "exists", side_effect=fake_exists), \
+             patch.dict(root_discovery_module.os.environ, {}, clear=True):
+            self.assertEqual(discovery.find_comfy_root(), "/opt/ComfyUI")
+
+
+class LaunchCommandBuilderTests(unittest.TestCase):
+    def build_command(self, root, worker=None, runtime=None):
+        builder = launch_builder_module.LaunchCommandBuilder()
+        worker = worker or {"id": "worker-a", "port": 8190}
+        runtime = runtime if runtime is not None else Namespace(database_url=None)
+        with patch.object(builder, "_get_runtime_args", return_value=runtime):
+            return builder.build_launch_command(worker, str(root))
+
+    def test_database_is_unique_and_stable_by_worker_id(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            first = self.build_command(root, {"id": "worker-a", "port": 8190})
+            renamed = self.build_command(root, {
+                "id": "worker-a", "port": 9001, "name": "Renamed", "cuda_device": 3,
+            })
+            second = self.build_command(root, {"id": "worker-b", "port": 8191})
+            database = first[first.index("--database-url") + 1]
+            self.assertEqual(database, renamed[renamed.index("--database-url") + 1])
+            self.assertNotEqual(database, second[second.index("--database-url") + 1])
+            self.assertTrue(database.startswith("sqlite:///" + root.as_posix() + "/"))
+            self.assertTrue(Path(database.removeprefix("sqlite:///")).parent.is_dir())
+            self.assertNotIn("--disable-assets", first)
+
+    def test_database_uses_effective_user_or_base_directory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            for extra_args, expected in [
+                (f'--user-directory "{root / "custom user"}"', root / "custom user"),
+                (f'--base-directory "{root / "custom base"}"', root / "custom base" / "user"),
+            ]:
+                with self.subTest(extra_args=extra_args):
+                    cmd = self.build_command(root, {
+                        "id": "worker-a", "port": 8190, "extra_args": extra_args,
+                    })
+                    database = cmd[cmd.index("--database-url") + 1]
+                    self.assertTrue(database.startswith("sqlite:///" + expected.as_posix() + "/"))
+            cmd = self.build_command(root, runtime=Namespace(
+                database_url="sqlite:///master.db", user_directory=str(root / "runtime user"),
+            ))
+            database = cmd[cmd.index("--database-url") + 1]
+            self.assertTrue(database.startswith("sqlite:///" + (root / "runtime user").as_posix() + "/"))
+            self.assertNotEqual(database, "sqlite:///master.db")
+
+    def test_relative_database_directories_use_worker_cwd(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory) / "ComfyUI"
+            root.mkdir()
+            (root / "main.py").touch()
+            launcher = Path(directory) / "launcher"
+            launcher.mkdir()
+            cases = [
+                (Namespace(database_url=None, user_directory="profiles"), "", root / "profiles"),
+                (Namespace(database_url=None, base_directory="data"), "", root / "data/user"),
+                (Namespace(database_url=None), "--user-directory=profiles", root / "profiles"),
+                (Namespace(database_url=None), "--base-directory data", root / "data/user"),
+            ]
+            for runtime, extra, expected in cases:
+                with self.subTest(runtime=runtime, extra=extra), \
+                     patch.object(os, "getcwd", return_value=str(launcher)):
+                    cmd = self.build_command(root, {
+                        "id": "worker-a", "port": 8190, "extra_args": extra,
+                    }, runtime)
+                    database = make_url(cmd[cmd.index("--database-url") + 1]).database
+                    self.assertEqual(Path(database).parent, expected / "distributed/workers")
+            self.assertFalse((launcher / "profiles").exists())
+            self.assertFalse((launcher / "data").exists())
+
+    def test_database_url_round_trips_special_characters_without_collisions(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            for name in ["user?profile", "user%3Fprofile"]:
+                with self.subTest(name=name):
+                    user = root / name
+                    runtime = Namespace(database_url=None, user_directory=str(user))
+                    # SQLAlchemy 2.0 cannot round-trip '?' in a filename. Fail
+                    # clearly on those versions rather than silently sharing a DB.
+                    sample = (user / "test.db").as_posix()
+                    serialized = URL.create("sqlite", database=sample).render_as_string()
+                    if make_url(serialized).database != sample:
+                        with self.assertRaisesRegex(ValueError, "SQLAlchemy.*database path"):
+                            self.build_command(root, runtime=runtime)
+                        self.assertFalse(user.exists())
+                        continue
+                    databases = []
+                    for worker_id in ["worker-a", "worker-b"]:
+                        cmd = self.build_command(root, {"id": worker_id, "port": 8190}, runtime)
+                        url = cmd[cmd.index("--database-url") + 1]
+                        database = make_url(url).database
+                        self.assertEqual(Path(database).parent, user / "distributed/workers")
+                        engine = create_engine(url)
+                        try:
+                            with engine.connect() as connection:
+                                actual = connection.exec_driver_sql("PRAGMA database_list").one()[2]
+                                self.assertEqual(Path(actual), Path(database))
+                        finally:
+                            engine.dispose()
+                        databases.append(database)
+                    self.assertNotEqual(*databases)
+
+    def test_explicit_database_and_disabled_assets_are_preserved(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            for extra in ["--database-url sqlite:///explicit.db", "--database-url=sqlite:///explicit.db", "--disable-assets"]:
+                with self.subTest(extra=extra):
+                    cmd = self.build_command(root, {"id": "worker-a", "port": 8190, "extra_args": extra})
+                    self.assertEqual(sum(arg.split("=")[0] == "--database-url" for arg in cmd), 0 if extra == "--disable-assets" else 1)
+                    self.assertFalse((root / "user").exists())
+
+    def test_older_comfyui_without_database_flag_keeps_existing_command(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            cmd = self.build_command(root, runtime=Namespace())
+            self.assertNotIn("--database-url", cmd)
+            self.assertFalse((root / "user").exists())
+
+    def test_worker_id_cannot_escape_database_directory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            databases = []
+            for worker_id in ["../outside", "a/b", "a_b"]:
+                cmd = self.build_command(root, {"id": worker_id, "port": 8190})
+                path = Path(cmd[cmd.index("--database-url") + 1].removeprefix("sqlite:///"))
+                self.assertTrue(path.is_relative_to(root / "user"))
+                databases.append(path)
+            self.assertEqual(len(set(databases)), 3)
+
+    def test_extra_args_cannot_silently_override_the_configured_port(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "main.py").touch()
+            for extra in ["--port 8189", "--port=8189"]:
+                with self.subTest(extra=extra), self.assertRaisesRegex(ValueError, "configured worker port"):
+                    self.build_command(root, {"id": "worker-a", "port": 8190, "extra_args": extra})
+
+    def test_inherits_runtime_layout_args_for_desktop(self):
+        builder = launch_builder_module.LaunchCommandBuilder()
+        runtime_args = Namespace(
+            listen="127.0.0.1",
+            base_directory="C:/Users/test/ComfyUI",
+            temp_directory=None,
+            input_directory="C:/Users/test/ComfyUI/input",
+            output_directory="C:/Users/test/ComfyUI/output",
+            user_directory="C:/Users/test/ComfyUI/user",
+            front_end_root="C:/Program Files/ComfyUI/web_custom_versions/desktop_app",
+            extra_model_paths_config=[["C:/Users/test/AppData/Roaming/ComfyUI/extra_models_config.yaml"]],
+            enable_manager=True,
+            disable_manager_ui=False,
+            enable_manager_legacy_ui=False,
+            windows_standalone_build=True,
+            log_stdout=True,
+            verbose="INFO",
+            enable_cors_header="*",
+        )
+        comfy_module = types.ModuleType("comfy")
+        comfy_cli_args = types.ModuleType("comfy.cli_args")
+        comfy_cli_args.args = runtime_args
+
+        worker_config = {
+            "port": 9001,
+            "extra_args": "--preview-method auto",
+        }
+
+        def fake_exists(path):
+            return path == "/desktop/ComfyUI/main.py"
+
+        with patch.dict(
+            sys.modules,
+            {"comfy": comfy_module, "comfy.cli_args": comfy_cli_args},
+            clear=False,
+        ), patch.object(launch_builder_module.os.path, "exists", side_effect=fake_exists):
+            cmd = builder.build_launch_command(worker_config, "/desktop/ComfyUI")
+
+        self.assertEqual(cmd[:2], ["/usr/bin/test-python", "/desktop/ComfyUI/main.py"])
+        self.assertIn("--listen", cmd)
+        self.assertIn("127.0.0.1", cmd)
+        self.assertIn("--base-directory", cmd)
+        self.assertIn("C:/Users/test/ComfyUI", cmd)
+        self.assertIn("--input-directory", cmd)
+        self.assertIn("--output-directory", cmd)
+        self.assertIn("--user-directory", cmd)
+        self.assertIn("--front-end-root", cmd)
+        self.assertIn("--extra-model-paths-config", cmd)
+        self.assertIn("C:/Users/test/AppData/Roaming/ComfyUI/extra_models_config.yaml", cmd)
+        self.assertIn("--enable-manager", cmd)
+        self.assertIn("--windows-standalone-build", cmd)
+        self.assertIn("--log-stdout", cmd)
+        self.assertIn("--disable-auto-launch", cmd)
+        self.assertIn("--enable-cors-header", cmd)
+        self.assertIn("*", cmd)
+        self.assertIn("--port", cmd)
+        self.assertIn("9001", cmd)
+        self.assertNotIn("--auto-launch", cmd)
+
+
+class ProcessLaunchPortTests(unittest.TestCase):
+    def test_launch_before_master_listens_uses_configured_master_port(self):
+        lifecycle_module = _load_process_module("lifecycle.py")
+        cli_args = types.ModuleType("comfy.cli_args")
+        cli_args.args = Namespace(port=8189)
+        for missing in [AttributeError("PromptServer has no port"), None]:
+            with self.subTest(missing=missing), tempfile.TemporaryDirectory() as directory:
+                manager = types.SimpleNamespace(
+                    find_comfy_root=lambda: directory,
+                    build_launch_command=lambda _worker, _root: ["python", "main.py"],
+                    processes={}, save_processes=lambda: None,
+                )
+                with patch.dict(sys.modules, {"comfy": types.ModuleType("comfy"), "comfy.cli_args": cli_args}), \
+                     patch.object(lifecycle_module, "get_server_port", side_effect=missing if isinstance(missing, Exception) else None, return_value=None), \
+                     patch.object(lifecycle_module, "validate_worker_port") as validate, \
+                     patch.object(lifecycle_module.subprocess, "Popen", return_value=types.SimpleNamespace(pid=1234)) as spawn:
+                    pid = lifecycle_module.ProcessLifecycle(manager).launch_worker({"id": "manual", "port": 8190})
+                validate.assert_called_once_with({"id": "manual", "port": 8190}, 8189, [])
+                spawn.assert_called_once()
+                self.assertEqual(pid, 1234)
+
+    def test_pre_listen_launch_still_rejects_the_configured_master_port(self):
+        lifecycle_module = _load_process_module("lifecycle.py")
+        cli_args = types.ModuleType("comfy.cli_args")
+        cli_args.args = Namespace(port=8189)
+        manager = types.SimpleNamespace(find_comfy_root=lambda: "/ComfyUI", processes={})
+        with patch.dict(sys.modules, {"comfy": types.ModuleType("comfy"), "comfy.cli_args": cli_args}), \
+             patch.object(lifecycle_module, "get_server_port", side_effect=AttributeError("port")), \
+             patch.object(lifecycle_module.subprocess, "Popen") as spawn:
+            with self.assertRaisesRegex(ValueError, "master port 8189"):
+                lifecycle_module.ProcessLifecycle(manager).launch_worker({"id": "manual", "port": 8189})
+        spawn.assert_not_called()
+
+    def test_conflict_is_rejected_before_building_or_spawning(self):
+        lifecycle_module = _load_process_module("lifecycle.py")
+        manager = types.SimpleNamespace(find_comfy_root=lambda: "/ComfyUI", processes={})
+        with patch.object(lifecycle_module.subprocess, "Popen") as spawn:
+            with self.assertRaisesRegex(ValueError, "master port 8189"):
+                lifecycle_module.ProcessLifecycle(manager).launch_worker({"id": "manual", "port": 8189})
+        spawn.assert_not_called()
+        self.assertEqual(manager.processes, {})
+
+    def test_available_port_reaches_existing_launch_path(self):
+        lifecycle_module = _load_process_module("lifecycle.py")
+        with tempfile.TemporaryDirectory() as directory:
+            manager = types.SimpleNamespace(
+                find_comfy_root=lambda: directory,
+                build_launch_command=lambda _worker, _root: ["python", "main.py", "--port", "8190"],
+                processes={}, save_processes=lambda: None,
+            )
+            with patch.object(lifecycle_module, "validate_worker_port") as validate, \
+                 patch.object(lifecycle_module.subprocess, "Popen", return_value=types.SimpleNamespace(pid=1234)) as spawn:
+                pid = lifecycle_module.ProcessLifecycle(manager).launch_worker({"id": "manual", "port": 8190})
+            validate.assert_called_once_with({"id": "manual", "port": 8190}, 8189, [])
+            spawn.assert_called_once()
+            self.assertEqual(pid, 1234)
+            self.assertEqual(manager.processes["manual"]["pid"], 1234)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -3,6 +3,7 @@ Async helper utilities for ComfyUI-Distributed.
 """
 import asyncio
 import threading
+import time
 import uuid
 import execution
 import server
@@ -104,7 +105,12 @@ class PromptValidationError(RuntimeError):
        super().__init__(f"Invalid prompt: {merged}")


-async def queue_prompt_payload(prompt_obj, workflow_meta=None, client_id=None):
+async def queue_prompt_payload(
+    prompt_obj,
+    workflow_meta=None,
+    client_id=None,
+    include_queue_metadata=False,
+):
    """Validate and queue a prompt via ComfyUI's prompt queue."""
    payload = {"prompt": prompt_obj}
    payload = prompt_server.trigger_on_prompt(payload)
@@ -117,7 +123,7 @@ async def queue_prompt_payload(prompt_obj, workflow_meta=None, client_id=None):
        node_errors = valid[3] if len(valid) > 3 else {}
        raise PromptValidationError(error_payload, node_errors)

-    extra_data = {}
+    extra_data = {"create_time": int(time.time() * 1000)}
    if workflow_meta:
        extra_data.setdefault("extra_pnginfo", {})["workflow"] = workflow_meta
    if client_id:
@@ -132,4 +138,12 @@ async def queue_prompt_payload(prompt_obj, workflow_meta=None, client_id=None):
    prompt_server.number = number + 1
    prompt_queue_item = (number, prompt_id, prompt, extra_data, valid[2], sensitive)
    prompt_server.prompt_queue.put(prompt_queue_item)
+
+    if include_queue_metadata:
+        return {
+            "prompt_id": prompt_id,
+            "number": number,
+            "node_errors": {},
+        }
+
    return prompt_id
@@ -42,6 +42,17 @@ MEMORY_CLEAR_DELAY = 0.5
 # Batch processing
 MAX_BATCH = int(os.environ.get('COMFYUI_MAX_BATCH', '20'))  # Maximum items per batch to prevent timeouts/OOM (~100MB chunks for 512x512 PNGs)

+# Compressed worker -> master result transfer (DistributedCollector)
+# Hard cap on one multipart request body. Must not exceed the master's
+# --max-upload-size (ComfyUI default: 100 MiB), which rejects larger requests.
+TRANSFER_MAX_REQUEST_BYTES = int(os.environ.get('COMFYUI_DISTRIBUTED_TRANSFER_MAX_REQUEST_BYTES', str(96 * 1024 * 1024)))
+# Target media bytes per request when batching several frames into one
+# request; a single frame may exceed this up to the hard cap above.
+TRANSFER_MAX_CHUNK_BYTES = min(
+    int(os.environ.get('COMFYUI_DISTRIBUTED_TRANSFER_CHUNK_BYTES', str(32 * 1024 * 1024))),
+    TRANSFER_MAX_REQUEST_BYTES,
+)
+
 # Heartbeat monitoring
 HEARTBEAT_INTERVAL = float(os.environ.get('COMFYUI_HEARTBEAT_INTERVAL', '10'))  # Heartbeat/check interval in seconds
 HEARTBEAT_TIMEOUT = int(os.environ.get('COMFYUI_HEARTBEAT_TIMEOUT', '60'))  # Worker heartbeat timeout in seconds (default 60s)
@@ -66,6 +66,25 @@ def normalize_host(value):
    return host.split("/")[0]


+def _split_host_and_port(host):
+    if not host:
+        return host, None
+
+    if host.startswith("["):
+        match = re.match(r"^(\[[^\]]+\])(?::(\d+))?$", host)
+        if match:
+            parsed_port = int(match.group(2)) if match.group(2) else None
+            return match.group(1), parsed_port
+        return host, None
+
+    if host.count(":") == 1:
+        candidate_host, candidate_port = host.rsplit(":", 1)
+        if candidate_port.isdigit():
+            return candidate_host, int(candidate_port)
+
+    return host, None
+
+
 def build_worker_url(worker, endpoint=""):
    """Construct the worker base URL with optional endpoint."""
    host = (worker.get("host") or "").strip()
@@ -126,12 +145,7 @@ def build_master_url(config=None, prompt_server_instance=None):
    prompt_server_instance = prompt_server_instance or server.PromptServer.instance
    master_cfg = (config or {}).get("master", {}) or {}
    configured_host = (master_cfg.get("host") or "").strip()
-    configured_port = master_cfg.get("port")
-    default_port = getattr(prompt_server_instance, "port", 8188) or 8188
-    try:
-        port = int(configured_port or default_port)
-    except (TypeError, ValueError):
-        port = int(default_port)
+    runtime_port = getattr(prompt_server_instance, "port", 8188) or 8188

    def _needs_https(hostname):
        hostname = hostname.lower()
@@ -149,10 +163,11 @@ def build_master_url(config=None, prompt_server_instance=None):
        if configured_host.startswith(("http://", "https://")):
            return configured_host.rstrip("/")

-        host = configured_host
+        host, explicit_port = _split_host_and_port(configured_host)
+        port = explicit_port if explicit_port is not None else int(runtime_port)
        scheme = "https" if _needs_https(host) or port == 443 else "http"
        default_port_for_scheme = 443 if scheme == "https" else 80
-        if configured_port is None and scheme == "https" and _needs_https(host):
+        if explicit_port is None and scheme == "https" and _needs_https(host):
            port = default_port_for_scheme
        port_part = "" if port == default_port_for_scheme else f":{port}"
        return f"{scheme}://{host}{port_part}"
@@ -160,7 +175,27 @@ def build_master_url(config=None, prompt_server_instance=None):
    address = getattr(prompt_server_instance, "address", "127.0.0.1") or "127.0.0.1"
    if address in ("0.0.0.0", "::"):
        address = "127.0.0.1"
+    port = int(runtime_port)
    scheme = "https" if port == 443 else "http"
    default_port_for_scheme = 443 if scheme == "https" else 80
    port_part = "" if port == default_port_for_scheme else f":{port}"
    return f"{scheme}://{address}{port_part}"
+
+
+def build_master_callback_url(worker, config=None, prompt_server_instance=None):
+    """Build the callback URL a specific worker should use to reach the master."""
+    prompt_server_instance = prompt_server_instance or server.PromptServer.instance
+
+    worker_type = str((worker or {}).get("type") or "").strip().lower()
+    worker_host = normalize_host((worker or {}).get("host"))
+    local_hosts = {"", "localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"}
+
+    is_local_worker = worker_type == "local" or worker_host in local_hosts
+    if is_local_worker:
+        port = int(getattr(prompt_server_instance, "port", 8188) or 8188)
+        scheme = "https" if port == 443 else "http"
+        default_port_for_scheme = 443 if scheme == "https" else 80
+        port_part = "" if port == default_port_for_scheme else f":{port}"
+        return f"{scheme}://127.0.0.1{port_part}"
+
+    return build_master_url(config=config, prompt_server_instance=prompt_server_instance)
@@ -0,0 +1,411 @@
+"""
+Compressed worker -> master image transfer.
+
+Workers encode their IMAGE batch with one of the formats below and POST it to
+the master as multipart/form-data chunks; the master decodes each chunk back
+into per-frame tensors. The goal is to cut network egress (e.g. cloud workers
+returning results to a local master), so formats range from bit-exact
+lossless to strongly compressed video.
+
+Formats
+-------
+legacy_png  Original behaviour: one JSON request per frame, uncompressed PNG
+            in base64. Kept for compatibility with unmodified masters.
+png         Lossless PNG per frame, sent as binary.
+ffv1        Lossless FFV1 video for the whole batch (good for frame sequences).
+jpeg, webp  Lossy per-frame stills.
+h264, h265, av1
+            Lossy video for the whole batch. Smallest by far for video
+            frame batches, where consecutive frames are similar.
+
+All formats quantize to 8-bit exactly like the legacy path did, so the
+lossless formats reproduce the legacy master tensors bit-for-bit.
+"""
+import io
+import math
+import os
+
+import numpy as np
+from PIL import Image
+
+LEGACY_FORMAT = "legacy_png"
+IMAGE_FORMATS = ("png", "jpeg", "webp")
+VIDEO_FORMATS = ("ffv1", "h264", "h265", "av1")
+LOSSLESS_FORMATS = (LEGACY_FORMAT, "png", "ffv1")
+TRANSFER_FORMATS = (LEGACY_FORMAT, "png", "ffv1", "jpeg", "webp", "h264", "h265", "av1")
+
+DEFAULT_TRANSFER_FORMAT = LEGACY_FORMAT
+DEFAULT_TRANSFER_QUALITY = 90
+
+TRANSFER_FORMAT_TOOLTIP = (
+    "How workers send images back to the master. "
+    "legacy_png: original uncompressed PNG (largest). "
+    "png / ffv1: lossless, identical result. "
+    "jpeg / webp: lossy stills. "
+    "h264 / h265 / av1: lossy video of the whole batch, smallest for frame sequences."
+)
+TRANSFER_QUALITY_TOOLTIP = (
+    "Quality for lossy transfer formats (ignored by lossless ones). "
+    "JPEG/WebP use it directly; video codecs map it to CRF "
+    "(90 -> h264/h265 CRF 13, av1 CRF 16)."
+)
+
+# encoder name, max CRF, container-friendly pixel format
+_VIDEO_CODECS = {
+    "ffv1": ("ffv1", None, "bgr0"),
+    "h264": ("libx264", 51, "yuv420p"),
+    "h265": ("libx265", 51, "yuv420p"),
+    "av1": ("libsvtav1", 63, "yuv420p"),
+}
+_VIDEO_RATE = 24
+# Upper bound on frames per video chunk, so one request never holds an
+# unbounded batch even when frames compress extremely well.
+MAX_VIDEO_CHUNK_FRAMES = 240
+# When sizing the next video chunk from observed bytes/frame, aim this far
+# below the limit so ordinary variation does not force a re-encode.
+VIDEO_CHUNK_SIZE_HEADROOM = 0.85
+
+
+class TransferCodecError(ValueError):
+    """Raised when a transfer payload cannot be encoded or decoded."""
+
+
+class FrameTooLargeError(TransferCodecError):
+    """A single encoded frame does not fit in one request.
+
+    Raised by encode_chunks before anything has been yielded for that frame;
+    callers that materialize all chunks first can therefore fail without
+    having delivered a partial batch.
+    """
+
+
+def normalize_format(value):
+    fmt = str(value or DEFAULT_TRANSFER_FORMAT).strip().lower()
+    if fmt not in TRANSFER_FORMATS:
+        raise TransferCodecError(
+            f"Unknown transfer format '{value}'. Expected one of: {', '.join(TRANSFER_FORMATS)}"
+        )
+    return fmt
+
+
+def normalize_quality(value):
+    try:
+        quality = int(value)
+    except (TypeError, ValueError):
+        quality = DEFAULT_TRANSFER_QUALITY
+    return max(1, min(100, quality))
+
+
+def quality_to_crf(quality, max_crf):
+    """Map 1-100 quality onto a codec CRF scale (0 = lossless/best).
+
+    The curve is chosen so the same quality number looks roughly the same
+    across JPEG/WebP and video codecs: 90 -> CRF 13 (h264/h265), 16 (av1);
+    80 -> 19 / 24; 100 -> 0.
+    """
+    quality = normalize_quality(quality)
+    return int(round(max_crf * (1.0 - quality / 100.0) ** 0.6))
+
+
+def tensor_batch_to_uint8(images):
+    """IMAGE tensor [B,H,W,C] float 0..1 -> uint8 numpy [B,H,W,3].
+
+    Uses the same truncating quantization as utils.image.tensor_to_pil so that
+    lossless formats reproduce the legacy transfer exactly, but clips first so
+    out-of-range values no longer wrap around.
+    """
+    arr = images.detach().cpu().float().numpy()
+    if arr.ndim == 3:
+        arr = arr[None, ...]
+    if arr.ndim != 4:
+        raise TransferCodecError(f"Expected IMAGE tensor [B,H,W,C], got shape {tuple(arr.shape)}")
+    channels = arr.shape[-1]
+    if channels == 1:
+        arr = np.repeat(arr, 3, axis=-1)
+    elif channels >= 3:
+        arr = arr[..., :3]
+    else:
+        raise TransferCodecError(f"Unsupported channel count {channels}")
+    return np.ascontiguousarray(np.clip(255.0 * arr, 0, 255).astype(np.uint8))
+
+
+def uint8_frame_to_tensor_array(frame):
+    """uint8 [H,W,3] -> float32 [1,H,W,3] numpy, matching utils.image.pil_to_tensor."""
+    return (frame.astype(np.float32) / 255.0)[None, ...]
+
+
+# --------------------------------------------------------------------------- #
+# Still images
+# --------------------------------------------------------------------------- #
+
+def encode_image_frame(frame, fmt, quality):
+    img = Image.fromarray(frame)
+    quality = normalize_quality(quality)
+    buf = io.BytesIO()
+    if fmt == "png":
+        img.save(buf, format="PNG", compress_level=4)  # ~same size as 6, 2x faster
+    elif fmt == "jpeg":
+        img.save(buf, format="JPEG", quality=quality, subsampling=0 if quality >= 90 else 2)
+    elif fmt == "webp":
+        img.save(buf, format="WEBP", quality=quality, method=4)
+    else:
+        raise TransferCodecError(f"'{fmt}' is not a still-image transfer format")
+    return buf.getvalue()
+
+
+def decode_image_frame(data):
+    try:
+        with Image.open(io.BytesIO(data)) as img:
+            return np.asarray(img.convert("RGB"), dtype=np.uint8)
+    except Exception as exc:
+        raise TransferCodecError(f"Failed to decode image frame: {exc}") from exc
+
+
+# --------------------------------------------------------------------------- #
+# Video
+# --------------------------------------------------------------------------- #
+
+def _import_av():
+    # SVT-AV1 prints a banner per encoder instance unless told otherwise.
+    os.environ.setdefault("SVT_LOG", "1")
+    try:
+        import av  # PyAV ships with ComfyUI
+    except ImportError as exc:
+        raise TransferCodecError("PyAV ('av') is required for video transfer formats") from exc
+    return av
+
+
+def video_codec_available(fmt):
+    if fmt not in _VIDEO_CODECS:
+        return False
+    try:
+        av = _import_av()
+        av.codec.Codec(_VIDEO_CODECS[fmt][0], "w")
+        return True
+    except Exception:
+        return False
+
+
+def _padded_size(fmt, pix_fmt, width, height):
+    """Encoder-friendly frame size; the decoder crops back to width x height.
+
+    4:2:0 needs even dimensions, and libx265 crashes on frames smaller than
+    its 64px CTU, so pad up to whichever is larger.
+    """
+    if pix_fmt == "yuv420p":
+        width, height = width + width % 2, height + height % 2
+    if fmt == "h265":
+        width, height = max(width, 64), max(height, 64)
+    return width, height
+
+
+def _pad_to(frame, width, height):
+    h, w = frame.shape[:2]
+    if h == height and w == width:
+        return frame
+    return np.pad(frame, ((0, height - h), (0, width - w), (0, 0)), mode="edge")
+
+
+class _VideoChunkWriter:
+    def __init__(self, fmt, quality, width, height):
+        av = _import_av()
+        self._av = av
+        codec_name, max_crf, pix_fmt = _VIDEO_CODECS[fmt]
+        self.fmt = fmt
+        self.pix_fmt = pix_fmt
+        self.width, self.height = _padded_size(fmt, pix_fmt, width, height)
+        self.buffer = io.BytesIO()
+        self.container = av.open(self.buffer, mode="w", format="matroska")
+        self.stream = self.container.add_stream(codec_name, rate=_VIDEO_RATE)
+        self.stream.width = self.width
+        self.stream.height = self.height
+        self.stream.pix_fmt = pix_fmt
+        options = {}
+        if max_crf is not None:
+            options["crf"] = str(quality_to_crf(quality, max_crf))
+        if fmt == "h264":
+            options["preset"] = "medium"
+        elif fmt == "h265":
+            options["preset"] = "fast"
+            options["x265-params"] = "log-level=error"
+        elif fmt == "av1":
+            options["preset"] = "8"
+        elif fmt == "ffv1":
+            options["level"] = "3"
+            options["slicecrc"] = "0"
+        self.stream.options = options
+        self.count = 0
+
+    def add(self, frame):
+        frame = _pad_to(frame, self.width, self.height)
+        vf = self._av.VideoFrame.from_ndarray(frame, format="rgb24")
+        for packet in self.stream.encode(vf):
+            self.container.mux(packet)
+        self.count += 1
+
+    def bytes_so_far(self):
+        return self.buffer.tell()
+
+    def close(self):
+        for packet in self.stream.encode():
+            self.container.mux(packet)
+        self.container.close()
+        return self.buffer.getvalue()
+
+
+def decode_video(data, width, height, expected_frames=None):
+    av = _import_av()
+    frames = []
+    try:
+        with av.open(io.BytesIO(data), mode="r") as container:
+            for vf in container.decode(video=0):
+                arr = vf.to_ndarray(format="rgb24")
+                frames.append(np.ascontiguousarray(arr[:height, :width]))
+    except TransferCodecError:
+        raise
+    except Exception as exc:
+        raise TransferCodecError(f"Failed to decode video chunk: {exc}") from exc
+    if expected_frames is not None and len(frames) != expected_frames:
+        raise TransferCodecError(
+            f"Video chunk decoded to {len(frames)} frames, expected {expected_frames}"
+        )
+    return frames
+
+
+# --------------------------------------------------------------------------- #
+# Chunking
+# --------------------------------------------------------------------------- #
+
+def encode_chunks(frames, fmt, quality, max_chunk_bytes, max_frame_bytes=None):
+    """Yield transfer chunks for a uint8 frame batch [B,H,W,3].
+
+    Each chunk is a dict:
+        {"format", "start_index", "count", "width", "height", "parts": [bytes, ...]}
+    Image formats carry one part per frame; video formats carry one part
+    (a Matroska file) holding `count` frames.
+
+    Size guarantees, measured on the finalized bytes (after encoder flush and
+    muxer finalization, not on encoder buffers):
+
+    * a chunk holding more than one frame never exceeds `max_chunk_bytes`;
+    * a chunk holding a single frame may exceed `max_chunk_bytes` but never
+      `max_frame_bytes` (defaults to `max_chunk_bytes`).
+
+    A frame that cannot fit in `max_frame_bytes` even on its own raises
+    FrameTooLargeError. Video chunks that come out too large are re-encoded
+    with fewer frames.
+    """
+    fmt = normalize_format(fmt)
+    if fmt == LEGACY_FORMAT:
+        raise TransferCodecError("legacy_png is sent through the JSON path, not encode_chunks")
+    total = int(frames.shape[0])
+    if total == 0:
+        return
+    height, width = int(frames.shape[1]), int(frames.shape[2])
+    max_chunk_bytes = max(1, int(max_chunk_bytes))
+    max_frame_bytes = max_chunk_bytes if max_frame_bytes is None else max(max_chunk_bytes, int(max_frame_bytes))
+
+    def _chunk(start, parts, count):
+        return {
+            "format": fmt,
+            "start_index": start,
+            "count": count,
+            "width": width,
+            "height": height,
+            "parts": parts,
+        }
+
+    def _too_large(index, size):
+        return FrameTooLargeError(
+            f"Frame {index} encodes to {size} bytes as {fmt}, above the {max_frame_bytes}-byte request limit. "
+            "Use a lossy format or lower quality, or raise the master's --max-upload-size together with "
+            "COMFYUI_DISTRIBUTED_TRANSFER_MAX_REQUEST_BYTES."
+        )
+
+    if fmt in IMAGE_FORMATS:
+        start, parts, size = 0, [], 0
+        for i in range(total):
+            data = encode_image_frame(frames[i], fmt, quality)
+            if len(data) > max_frame_bytes:
+                raise _too_large(i, len(data))
+            if parts and size + len(data) > max_chunk_bytes:
+                yield _chunk(start, parts, len(parts))
+                start, parts, size = i, [], 0
+            parts.append(data)
+            size += len(data)
+        if parts:
+            yield _chunk(start, parts, len(parts))
+        return
+
+    start = 0
+    budget = MAX_VIDEO_CHUNK_FRAMES
+    while start < total:
+        want = min(budget, total - start)
+        data, count = _encode_video_range(frames, start, want, fmt, quality, width, height, max_chunk_bytes)
+        if len(data) <= max_chunk_bytes or (count == 1 and len(data) <= max_frame_bytes):
+            yield _chunk(start, [data], count)
+            start += count
+            per_frame = len(data) / count
+            budget = max(1, min(MAX_VIDEO_CHUNK_FRAMES, int(max_chunk_bytes * VIDEO_CHUNK_SIZE_HEADROOM / per_frame)))
+            continue
+        if count == 1:
+            raise _too_large(start, len(data))
+        # Finalized chunk overshot: retry this range with proportionally fewer
+        # frames. Strictly fewer than `count`, so this always terminates.
+        estimate = int(count * max_chunk_bytes * VIDEO_CHUNK_SIZE_HEADROOM / len(data))
+        budget = max(1, min(count - 1, estimate))
+
+
+def _encode_video_range(frames, start, count, fmt, quality, width, height, stop_after_bytes):
+    """Encode frames[start:start+count] as one finalized video.
+
+    Stops feeding frames early once the muxed output already exceeds
+    `stop_after_bytes`, since the chunk is then known to be too large and will
+    be re-encoded smaller; this bounds wasted work. Encoder lookahead means the
+    pre-flush size underestimates the final size, so the caller must still
+    check the returned (finalized) bytes. Returns (bytes, frames_encoded).
+    """
+    writer = _VideoChunkWriter(fmt, quality, width, height)
+    for i in range(start, start + count):
+        writer.add(frames[i])
+        if writer.bytes_so_far() > stop_after_bytes:
+            break
+    return writer.close(), writer.count
+
+
+def decode_chunk(envelope, parts):
+    """Decode one received chunk into a list of uint8 [H,W,3] frames."""
+    fmt = normalize_format(envelope.get("format"))
+    if fmt == LEGACY_FORMAT:
+        raise TransferCodecError("legacy_png chunks are not sent as multipart")
+    count = envelope.get("count")
+    width = envelope.get("width")
+    height = envelope.get("height")
+    for name, value in (("count", count), ("width", width), ("height", height)):
+        if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+            raise TransferCodecError(f"envelope.{name}: expected positive integer")
+    if not parts:
+        raise TransferCodecError("chunk has no media parts")
+
+    if fmt in IMAGE_FORMATS:
+        if len(parts) != count:
+            raise TransferCodecError(f"expected {count} image parts, got {len(parts)}")
+        frames = [decode_image_frame(p) for p in parts]
+    else:
+        if len(parts) != 1:
+            raise TransferCodecError(f"expected 1 video part, got {len(parts)}")
+        frames = decode_video(parts[0], width, height, expected_frames=count)
+
+    for frame in frames:
+        if frame.shape[0] != height or frame.shape[1] != width:
+            raise TransferCodecError(
+                f"decoded frame is {frame.shape[1]}x{frame.shape[0]}, expected {width}x{height}"
+            )
+    return frames
+
+
+def describe_ratio(sent_bytes, raw_bytes):
+    if sent_bytes <= 0:
+        return "n/a"
+    ratio = raw_bytes / sent_bytes
+    return f"{ratio:.1f}x" if math.isfinite(ratio) else "n/a"
@@ -178,11 +178,32 @@ export function createApiClient(baseUrl) {
                    return { ok: false, status: response.status, queueRemaining: null };
                }

-                const data = await response.json().catch(() => ({}));
+                let data;
+                try {
+                    data = await response.json();
+                } catch {
+                    return { ok: false, status: response.status, queueRemaining: null };
+                }
+
+                if (!data || typeof data !== "object" || Array.isArray(data)) {
+                    return { ok: false, status: response.status, queueRemaining: null };
+                }
+
+                const execInfo = data.exec_info;
+                if (!execInfo || typeof execInfo !== "object" || Array.isArray(execInfo)) {
+                    return { ok: false, status: response.status, queueRemaining: null };
+                }
+
+                const rawQueueRemaining = execInfo.queue_remaining;
+                const queueRemaining = Number(rawQueueRemaining);
+                if (!Number.isFinite(queueRemaining)) {
+                    return { ok: false, status: response.status, queueRemaining: null };
+                }
+
                return {
                    ok: true,
                    status: response.status,
-                    queueRemaining: data.exec_info?.queue_remaining || 0,
+                    queueRemaining: Math.max(0, queueRemaining),
                };
            } finally {
                clearTimeout(timeoutId);
@@ -2,7 +2,6 @@ import { app } from "/scripts/app.js";
 import { ENDPOINTS } from "./constants.js";

 const NODE_CLASS = "DistributedValue";
-const CONVERTED_WIDGET = "converted-widget";
 const DYNAMIC_DEFAULT_WIDGET = "_dv_default";
 const DYNAMIC_WORKER_WIDGET_PREFIX = "_dv_worker_";
 const WORKERS_CHANGED_EVENT = "distributed:workers-changed";
@@ -42,15 +41,13 @@ function getDynamicWorkerWidgets(node) {
    return (node.widgets || []).filter((w) => w.name.startsWith(DYNAMIC_WORKER_WIDGET_PREFIX));
 }

-function hideWidgetForGood(node, widget, suffix = "") {
+function hideWidgetForGood(widget) {
    if (!widget) return;
-    if (typeof widget.type === "string" && widget.type.startsWith(CONVERTED_WIDGET)) return;
-
-    widget.origType = widget.type;
-    widget.origComputeSize = widget.computeSize;
-    widget.origSerializeValue = widget.serializeValue;
-    widget.computeSize = () => [0, -4];
-    widget.type = `${CONVERTED_WIDGET}${suffix}`;
+    // These are serialized backing fields, not widgets converted into sockets.
+    // Keep their native type/serializer and mutate the shared options in place
+    // so both the classic canvas and Nodes 2.0 suppress the whole widget row.
+    widget.options ??= {};
+    widget.options.hidden = true;

    // Hide any attached DOM element (multiline widgets).
    if (widget.element) widget.element.style.display = "none";
@@ -58,14 +55,14 @@ function hideWidgetForGood(node, widget, suffix = "") {

    if (widget.linkedWidgets) {
        for (const linked of widget.linkedWidgets) {
-            hideWidgetForGood(node, linked, `:${widget.name}`);
+            hideWidgetForGood(linked);
        }
    }
 }

 function hideRawWidgets(node) {
-    hideWidgetForGood(node, getRawDefaultWidget(node), ":default_value");
-    hideWidgetForGood(node, getRawWorkerValuesWidget(node), ":worker_values");
+    hideWidgetForGood(getRawDefaultWidget(node));
+    hideWidgetForGood(getRawWorkerValuesWidget(node));
 }

 function removeDynamicDefaultWidget(node) {
@@ -4,7 +4,7 @@ import { TIMEOUTS, NODE_CLASSES, generateUUID } from './constants.js';
 import { checkAllWorkerStatuses, getWorkerUrl } from './workerLifecycle.js';

 export function setupInterceptor(extension) {
-    api.queuePrompt = async (number, prompt) => {
+    api.queuePrompt = async (number, prompt, ...rest) => {
        if (extension.isEnabled) {
            const hasCollector = findNodesByClass(prompt.output, NODE_CLASSES.DISTRIBUTED_COLLECTOR).length > 0;
            const hasDistUpscale = findNodesByClass(prompt.output, NODE_CLASSES.UPSCALE_DISTRIBUTED).length > 0;
@@ -18,7 +18,7 @@ export function setupInterceptor(extension) {
                return result;
            }
        }
-        return extension.originalQueuePrompt(number, prompt);
+        return extension.originalQueuePrompt(number, prompt, ...rest);
    };
 }

@@ -42,6 +42,15 @@ export async function detectMasterIP(extension) {
            if (shouldAutoPopulate) {
                extension.log(`Auto-populating workers based on ${extension.cudaDeviceCount} CUDA devices (excluding master on CUDA ${extension.masterCudaDevice})`, "info");

+                const workerCount = extension.cudaDeviceCount - (
+                    Number.isInteger(extension.masterCudaDevice) &&
+                    extension.masterCudaDevice >= 0 &&
+                    extension.masterCudaDevice < extension.cudaDeviceCount ? 1 : 0
+                );
+                const workerPorts = data.local_worker_ports;
+                if (!Array.isArray(workerPorts) || workerPorts.length !== workerCount) {
+                    throw new Error("Could not allocate enough available local worker ports; check the server log");
+                }
                const newWorkers = [];
                let workerNum = 1;
                let portOffset = 0;
@@ -56,7 +65,7 @@ export async function detectMasterIP(extension) {
                        id: generateUUID(),
                        name: `Worker ${workerNum}`,
                        host: isRunpod ? null : "localhost",
-                        port: 8189 + portOffset,
+                        port: workerPorts[portOffset],
                        cuda_device: i,
                        enabled: true,
                        extra_args: isRunpod ? "--listen" : "",
@@ -72,7 +72,7 @@ export function renderSettingsSection(extension) {
        createCheckboxSetting(
            "setting-debug",
            "Debug Mode",
-            "Enable verbose logging in the browser console.",
+            "Enable verbose logging in the browser console and ComfyUI server output.",
            extension.config?.settings?.debug || false,
            (event) => extension._updateSetting("debug", event.target.checked)
        )
@@ -100,7 +100,7 @@ export function renderSettingsSection(extension) {
        createNumberSetting(
            "setting-worker-timeout",
            "Worker Timeout",
-            "Seconds without a heartbeat before a worker is considered timed out. Default 60.",
+            "Maximum result-wait and heartbeat inactivity period before recovery begins. Busy workers may receive additional grace. Default: 60 seconds.",
            extension.config?.settings?.worker_timeout_seconds ?? 60,
            10,
            1,
@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createApiClient } from "../apiClient.js";
+
+describe("apiClient probeWorker", () => {
+    let originalFetch;
+
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn();
+    });
+
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        vi.restoreAllMocks();
+    });
+
+    it("returns ok=true when /prompt returns valid exec_info payload", async () => {
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: vi.fn().mockResolvedValue({ exec_info: { queue_remaining: 2 } }),
+        });
+
+        const client = createApiClient("http://127.0.0.1:8188");
+        const result = await client.probeWorker("http://worker.local:8190", 1000);
+
+        expect(result).toEqual({ ok: true, status: 200, queueRemaining: 2 });
+    });
+
+    it("returns ok=false on non-200 responses", async () => {
+        globalThis.fetch.mockResolvedValue({
+            ok: false,
+            status: 503,
+            json: vi.fn(),
+        });
+
+        const client = createApiClient("http://127.0.0.1:8188");
+        const result = await client.probeWorker("http://worker.local:8190", 1000);
+
+        expect(result).toEqual({ ok: false, status: 503, queueRemaining: null });
+    });
+
+    it("returns ok=false when response JSON is invalid", async () => {
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: vi.fn().mockRejectedValue(new Error("invalid json")),
+        });
+
+        const client = createApiClient("http://127.0.0.1:8188");
+        const result = await client.probeWorker("http://worker.local:8190", 1000);
+
+        expect(result).toEqual({ ok: false, status: 200, queueRemaining: null });
+    });
+
+    it("returns ok=false when exec_info is missing", async () => {
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: vi.fn().mockResolvedValue({}),
+        });
+
+        const client = createApiClient("http://127.0.0.1:8188");
+        const result = await client.probeWorker("http://worker.local:8190", 1000);
+
+        expect(result).toEqual({ ok: false, status: 200, queueRemaining: null });
+    });
+
+    it("returns ok=false when queue_remaining is not numeric", async () => {
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: vi.fn().mockResolvedValue({ exec_info: { queue_remaining: "n/a" } }),
+        });
+
+        const client = createApiClient("http://127.0.0.1:8188");
+        const result = await client.probeWorker("http://worker.local:8190", 1000);
+
+        expect(result).toEqual({ ok: false, status: 200, queueRemaining: null });
+    });
+
+    it("clamps negative queue_remaining to zero", async () => {
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: vi.fn().mockResolvedValue({ exec_info: { queue_remaining: -5 } }),
+        });
+
+        const client = createApiClient("http://127.0.0.1:8188");
+        const result = await client.probeWorker("http://worker.local:8190", 1000);
+
+        expect(result).toEqual({ ok: true, status: 200, queueRemaining: 0 });
+    });
+});
@@ -0,0 +1,120 @@
+import { readFileSync } from "node:fs";
+import vm from "node:vm";
+import { describe, expect, it, vi } from "vitest";
+
+// Evaluate this repository's browser entrypoint without needing a ComfyUI server.
+// The real-renderer acceptance additionally checks the input rows in Chromium.
+const source = readFileSync(new URL("../distributedValue.js", import.meta.url), "utf8")
+    .replace(/^import .*;\r?\n/gm, "");
+
+function setup({ connected = false, targetType = "STRING" } = {}) {
+    let extension;
+    const listeners = new Map();
+    const tasks = [];
+    const workers = [
+        { id: "gpu-a", name: "GPU A", enabled: true },
+        { id: "gpu-b", name: "GPU B", enabled: true },
+        { id: "off", name: "Disabled", enabled: false },
+    ];
+    const target = {
+        inputs: [{ name: "value" }],
+        widgets: [{ name: "value", type: targetType === "INT" ? "number" : "string", options: { step: 1, precision: 0 } }],
+    };
+    const graph = { links: { 1: { target_id: 2, target_slot: 0 } }, getNodeById: () => target };
+    const raw = ["default_value", "worker_values"].map((name, index) => ({
+        name,
+        type: "text",
+        value: index === 0 ? "saved default" : '{"1":"saved worker"}',
+        options: { multiline: false },
+        computeSize: vi.fn(() => [200, 20]),
+        serializeValue: vi.fn(function () { return this.value; }),
+    }));
+    const node = {
+        comfyClass: "DistributedValue", graph, widgets: [...raw], size: [200, 100],
+        inputs: raw.map(w => ({ name: w.name, widget: { name: w.name }, link: null })),
+        outputs: [{ links: connected ? [1] : [] }],
+        computeSize: () => [200, 100], setSize: vi.fn(), setDirtyCanvas: vi.fn(),
+        addWidget(type, name, value, callback, options) {
+            const widget = { type, name, value, callback, options };
+            this.widgets.push(widget);
+            return widget;
+        },
+        configure(data) {
+            data.widgets_values.forEach((value, i) => { this.widgets[i].value = value; });
+            return "configured";
+        },
+    };
+    vm.runInNewContext(source, {
+        app: { graph, registerExtension: ext => { extension = ext; } },
+        ENDPOINTS: { CONFIG: "/distributed/config" },
+        fetch: async () => ({ ok: true, json: async () => ({ workers }) }),
+        window: { addEventListener: (name, handler) => listeners.set(name, handler) },
+        setTimeout: callback => { tasks.push(callback); }, console,
+    }, { filename: "distributedValue.js" });
+    return { node, raw, extension, listeners, tasks, flush: () => { while (tasks.length) tasks.shift()(); } };
+}
+
+describe("Distributed Value internal widget visibility", () => {
+    it("hides raw fields natively without converting their types or replacing their options", async () => {
+        const h = setup();
+        const options = h.raw.map(w => w.options);
+        const sizes = h.raw.map(w => w.computeSize);
+        const serializers = h.raw.map(w => w.serializeValue);
+        const slots = h.node.inputs;
+        await h.extension.nodeCreated(h.node);
+
+        for (const [i, widget] of h.raw.entries()) {
+            expect(widget.type).toBe("text");
+            expect(widget.options).toBe(options[i]);
+            expect(widget.options.hidden).toBe(true);
+            expect(widget.computeSize).toBe(sizes[i]);
+            expect(widget.serializeValue).toBe(serializers[i]);
+            expect(h.node.widgets[i]).toBe(widget);
+        }
+        expect(h.node.inputs).toBe(slots);
+        expect(h.node.widgets.slice(2).map(w => w.label)).toEqual(["default_value", "GPU A", "GPU B"]);
+        expect(h.node.widgets.slice(2).every(w => !w.options.hidden)).toBe(true);
+    });
+
+    it("keeps typed edits in the original serialized fields across rebuild/configure", async () => {
+        const h = setup({ connected: true, targetType: "INT" });
+        await h.extension.nodeCreated(h.node);
+        h.node.widgets.find(w => w.name === "_dv_default").callback(42);
+        h.node.widgets.find(w => w.name === "_dv_worker_1").callback(7);
+        h.node.widgets.find(w => w.name === "_dv_worker_2").callback(9);
+        const values = h.raw.map(w => w.serializeValue());
+        expect(values[0]).toBe(42);
+        expect(JSON.parse(values[1])).toMatchObject({
+            _type: "INT", 1: "7", 2: "9", _by_worker_id: { "gpu-a": "7", "gpu-b": "9" },
+        });
+        expect(h.node.configure({ widgets_values: values })).toBe("configured");
+        h.flush();
+        expect(h.raw.map(w => w.serializeValue())).toEqual(values);
+        expect(h.raw.every(w => w.options.hidden && w.type === "text")).toBe(true);
+        expect(h.node.widgets.slice(2).map(w => w.value)).toEqual([42, 7, 9]);
+    });
+
+    it("reapplies visibility on worker refresh without duplicating raw or dynamic fields", async () => {
+        const h = setup();
+        await h.extension.nodeCreated(h.node);
+        h.raw[0].options.hidden = false;
+        await h.listeners.get("distributed:workers-changed")({ detail: { workers: [
+            { id: "gpu-b", name: "Renamed B", enabled: true },
+        ] } });
+        expect(h.raw.every(w => w.options.hidden)).toBe(true);
+        expect(h.node.widgets.map(w => w.name)).toEqual(["default_value", "worker_values", "_dv_default", "_dv_worker_1"]);
+        expect(h.node.widgets[3].label).toBe("Renamed B");
+    });
+
+    it("hides linked backing widgets and handles absent options without altering serializers", async () => {
+        const h = setup();
+        delete h.raw[1].options;
+        const linked = { type: "text", options: {}, serializeValue: vi.fn(() => "linked") };
+        h.raw[0].linkedWidgets = [linked];
+        await h.extension.nodeCreated(h.node);
+        expect(h.raw[1].options.hidden).toBe(true);
+        expect(linked.options.hidden).toBe(true);
+        expect(linked.type).toBe("text");
+        expect(linked.serializeValue()).toBe("linked");
+    });
+});
@@ -1,15 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { buildWorkerWebSocketUrl } from "../urlUtils.js";
-
-
-describe("execution decision helpers", () => {
-    it("buildWorkerWebSocketUrl converts http/https to ws/wss", () => {
-        expect(buildWorkerWebSocketUrl("http://worker.local:8188")).toBe(
-            "ws://worker.local:8188/distributed/worker_ws"
-        );
-        expect(buildWorkerWebSocketUrl("https://worker.example.com")).toBe(
-            "wss://worker.example.com/distributed/worker_ws"
-        );
-    });
-});
@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { detectMasterIP } from "../masterDetection.js";
+
+describe("automatic local worker ports", () => {
+    let originalWindow;
+    beforeEach(() => {
+        originalWindow = globalThis.window;
+        globalThis.window = { location: { hostname: "localhost", port: "443" } };
+    });
+    afterEach(() => { globalThis.window = originalWindow; });
+
+    function makeExtension(overrides = {}) {
+        return {
+            config: { workers: [], settings: {}, master: {} },
+            log: vi.fn(),
+            api: {
+                getNetworkInfo: vi.fn().mockResolvedValue({
+                    cuda_device: 0, cuda_device_count: 3,
+                    master_port: 8189, local_worker_ports: [8191, 8193],
+                    ...overrides,
+                }),
+                updateMaster: vi.fn().mockResolvedValue({}),
+                updateWorker: vi.fn().mockResolvedValue({}),
+                updateSetting: vi.fn().mockResolvedValue({}),
+            },
+            ui: { updateMasterDisplay: vi.fn() },
+            app: {},
+            loadConfig: vi.fn().mockResolvedValue(),
+        };
+    }
+
+    it("uses server-allocated ports, not hardcoded ports or the browser proxy port", async () => {
+        const extension = makeExtension();
+        await detectMasterIP(extension);
+        expect(extension.config.workers.map(worker => worker.port)).toEqual([8191, 8193]);
+        expect(extension.config.workers.map(worker => worker.cuda_device)).toEqual([1, 2]);
+        expect(extension.api.updateWorker).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not overwrite an existing manually configured worker", async () => {
+        const extension = makeExtension();
+        const worker = { id: "manual", host: "localhost", port: 8189 };
+        extension.config.workers = [worker];
+        await detectMasterIP(extension);
+        expect(extension.config.workers).toEqual([worker]);
+        expect(extension.api.updateWorker).not.toHaveBeenCalled();
+    });
+
+    it("fails without partially saving workers if not enough ports are available", async () => {
+        const extension = makeExtension({ local_worker_ports: [8191] });
+        await detectMasterIP(extension);
+        expect(extension.config.workers).toEqual([]);
+        expect(extension.api.updateWorker).not.toHaveBeenCalled();
+        expect(extension.api.updateSetting).not.toHaveBeenCalled();
+        expect(extension.log).toHaveBeenCalledWith(expect.stringContaining("port"), "error");
+    });
+
+    it("preserves Runpod worker host and launch settings", async () => {
+        globalThis.window.location.hostname = "pod-8189.proxy.runpod.net";
+        const extension = makeExtension();
+        await detectMasterIP(extension);
+        expect(extension.config.workers.map(worker => worker.port)).toEqual([8191, 8193]);
+        expect(extension.config.workers.every(worker => worker.host === null && worker.extra_args === "--listen")).toBe(true);
+    });
+});
@@ -106,11 +106,6 @@ describe("buildWorkerWebSocketUrl", () => {
            "wss://worker.example.com/distributed/worker_ws"
        );
    });
-
-    it("always appends /distributed/worker_ws", () => {
-        const url = buildWorkerWebSocketUrl("http://worker.local:8188");
-        expect(url.endsWith("/distributed/worker_ws")).toBe(true);
-    });
 });


@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { getWorkerUrl } from "../workerLifecycle.js";


-describe("workerLifecycle URL construction", () => {
+describe("workerLifecycle URL wiring", () => {
    let originalWindow;

    beforeEach(() => {
@@ -22,31 +22,9 @@ describe("workerLifecycle URL construction", () => {
        globalThis.window = originalWindow;
    });

-    it("builds local worker URL with explicit local port", () => {
+    // URL variants are covered in urlUtils.test.js; keep the wrapper wiring here.
+    it("forwards the worker and endpoint using window.location", () => {
        const worker = { id: "w1", port: 8189, type: "local" };
        expect(getWorkerUrl({}, worker, "/prompt")).toBe("http://127.0.0.1:8189/prompt");
    });
-
-    it("builds remote worker URL with host:port", () => {
-        const worker = { id: "w2", host: "worker.example.com", port: 9000, type: "remote" };
-        expect(getWorkerUrl({}, worker, "/prompt")).toBe("http://worker.example.com:9000/prompt");
-    });
-
-    it("builds cloud worker URL as https", () => {
-        const worker = { id: "w3", host: "cloud.example.com", port: 443, type: "cloud" };
-        expect(getWorkerUrl({}, worker, "/prompt")).toBe("https://cloud.example.com/prompt");
-    });
-
-    it("rewrites runpod proxy hostname for local worker ports", () => {
-        globalThis.window = {
-            location: {
-                hostname: "podabc.proxy.runpod.net",
-                protocol: "https:",
-                port: "",
-                origin: "https://podabc.proxy.runpod.net",
-            },
-        };
-        const worker = { id: "w4", port: 8189, type: "local" };
-        expect(getWorkerUrl({}, worker, "/prompt")).toBe("https://podabc-8189.proxy.runpod.net/prompt");
-    });
 });
@@ -0,0 +1,97 @@
+"""Host-local worker port selection and launch preflight (no ComfyUI imports)."""
+import errno
+import os
+import socket
+from urllib.parse import urlsplit
+
+
+def _port_number(value):
+    try:
+        port = int(value)
+    except (TypeError, ValueError):
+        raise ValueError("Worker port must be an integer between 1 and 65535") from None
+    if isinstance(value, (bool, float)) or not 1 <= port <= 65535:
+        raise ValueError("Worker port must be an integer between 1 and 65535")
+    return port
+
+
+def _local_config(worker):
+    local_hosts = ("localhost", "127.0.0.1", "0.0.0.0", "::1", "::")
+    host = (worker.get("host") or "localhost").strip().lower()
+    if worker.get("type") == "local" or host in local_hosts:
+        return True
+    try:
+        host = urlsplit(host if "://" in host else "//" + host).hostname
+    except ValueError:
+        return False
+    return host in local_hosts
+
+
+def _reserved_ports(workers, exclude_id=None):
+    reserved = {}
+    for worker in workers:
+        if exclude_id is not None and str(worker.get("id")) == str(exclude_id):
+            continue
+        if not _local_config(worker):
+            continue
+        try:
+            port = _port_number(worker.get("port"))
+        except ValueError:
+            continue
+        reserved[port] = worker.get("name") or worker.get("id") or "another local worker"
+    return reserved
+
+
+def is_port_available(port):
+    """Match asyncio's address reuse while rejecting active IPv4/IPv6 listeners."""
+    addresses = [(socket.AF_INET, "0.0.0.0")]
+    if socket.has_ipv6:
+        addresses.append((socket.AF_INET6, "::"))
+    for family, address in addresses:
+        try:
+            with socket.socket(family, socket.SOCK_STREAM) as probe:
+                if os.name != "nt":
+                    # Like asyncio, allow a restart while old connections are
+                    # in TIME_WAIT. Do not enable SO_REUSEPORT.
+                    probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                elif hasattr(socket, "SO_EXCLUSIVEADDRUSE"):
+                    # Windows SO_REUSEADDR can steal an active listener's port.
+                    probe.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+                probe.bind((address, port))
+                probe.listen(1)
+        except OSError as exc:
+            if family == socket.AF_INET6 and exc.errno in (errno.EAFNOSUPPORT, errno.EADDRNOTAVAIL):
+                continue
+            return False
+    return True
+
+
+def allocate_worker_ports(master_port, workers, count):
+    """Select ports above the actual master, skipping reservations/listeners.
+
+    This is a snapshot, not a reservation. Launch must validate again because
+    another process can claim a suggested port before the user starts a worker.
+    """
+    master_port = _port_number(master_port)
+    reserved = _reserved_ports(workers)
+    selected = []
+    if count == 0:
+        return selected
+    for port in range(master_port + 1, 65536):
+        if port not in reserved and is_port_available(port):
+            selected.append(port)
+            if len(selected) == count:
+                return selected
+    raise ValueError(f"Not enough available worker ports above master port {master_port}; need {count}")
+
+
+def validate_worker_port(worker, master_port, workers):
+    """Reject conflicts without silently changing a configured worker port."""
+    port = _port_number(worker.get("port"))
+    if port == _port_number(master_port):
+        raise ValueError(f"Worker port {port} conflicts with the master port {master_port}; choose another worker port")
+    reserved = _reserved_ports(workers, exclude_id=worker.get("id"))
+    if port in reserved:
+        raise ValueError(f"Worker port {port} is assigned to local worker {reserved[port]}; choose another worker port")
+    if not is_port_available(port):
+        raise ValueError(f"Worker port {port} is already in use on this host; choose another worker port")
@@ -1,4 +1,5 @@
 import glob
+import hashlib
 import os
 import shlex
 import shutil
@@ -10,6 +11,62 @@ from ...utils.process import get_python_executable
 class LaunchCommandBuilder:
    """Build command-lines for launching worker ComfyUI processes."""

+    def _extend_arg(self, cmd, flag, value):
+        if value in (None, "", [], ()):
+            return
+        cmd.extend([flag, str(value)])
+
+    def _extend_grouped_args(self, cmd, flag, values):
+        for group in values or []:
+            flattened = [str(item) for item in group if item]
+            if flattened:
+                cmd.append(flag)
+                cmd.extend(flattened)
+
+    def _get_runtime_args(self):
+        try:
+            from comfy.cli_args import args
+            return args
+        except Exception as exc:
+            debug_log(f"Could not read current ComfyUI CLI args for worker launch: {exc}")
+            return None
+
+    def _build_runtime_launch_args(self):
+        args = self._get_runtime_args()
+        if args is None:
+            return []
+
+        inherited = []
+        self._extend_arg(inherited, "--listen", getattr(args, "listen", None))
+        self._extend_arg(inherited, "--base-directory", getattr(args, "base_directory", None))
+        self._extend_arg(inherited, "--temp-directory", getattr(args, "temp_directory", None))
+        self._extend_arg(inherited, "--input-directory", getattr(args, "input_directory", None))
+        self._extend_arg(inherited, "--output-directory", getattr(args, "output_directory", None))
+        self._extend_arg(inherited, "--user-directory", getattr(args, "user_directory", None))
+        self._extend_arg(inherited, "--front-end-root", getattr(args, "front_end_root", None))
+        self._extend_grouped_args(
+            inherited,
+            "--extra-model-paths-config",
+            getattr(args, "extra_model_paths_config", None),
+        )
+
+        if getattr(args, "enable_manager", False):
+            inherited.append("--enable-manager")
+        if getattr(args, "disable_manager_ui", False):
+            inherited.append("--disable-manager-ui")
+        if getattr(args, "enable_manager_legacy_ui", False):
+            inherited.append("--enable-manager-legacy-ui")
+        if getattr(args, "windows_standalone_build", False):
+            inherited.append("--windows-standalone-build")
+        if getattr(args, "log_stdout", False):
+            inherited.append("--log-stdout")
+
+        verbose = getattr(args, "verbose", None)
+        if verbose and verbose != "INFO":
+            inherited.extend(["--verbose", str(verbose)])
+
+        return inherited
+
    def _find_windows_terminal(self):
        """Find Windows Terminal executable."""
        possible_paths = [
@@ -31,6 +88,51 @@ class LaunchCommandBuilder:
            return wt_path
        return None

+    @staticmethod
+    def _arg_value(cmd, flag):
+        """Return the last value, matching argparse's override semantics."""
+        value = None
+        for index, arg in enumerate(cmd):
+            if arg == flag and index + 1 < len(cmd):
+                value = cmd[index + 1]
+            elif arg.startswith(flag + "="):
+                value = arg.split("=", 1)[1]
+        return value
+
+    def _add_worker_database(self, cmd, worker_config, comfy_root):
+        args = self._get_runtime_args()
+        # The parsed namespace advertises support without launching ComfyUI
+        # (or importing another checkout's argument parser).
+        if args is None or not hasattr(args, "database_url"):
+            return
+        if any(arg.split("=", 1)[0] in ("--database-url", "--disable-assets") for arg in cmd):
+            return
+
+        user_directory = self._arg_value(cmd, "--user-directory")
+        base_directory = self._arg_value(cmd, "--base-directory")
+        if not user_directory:
+            user_directory = os.path.join(base_directory or comfy_root, "user")
+        if not os.path.isabs(user_directory):
+            # Popen uses comfy_root as cwd, which can differ from the master's.
+            user_directory = os.path.join(comfy_root, user_directory)
+        database_directory = os.path.abspath(os.path.join(user_directory, "distributed", "workers"))
+        # Hash the immutable ID: names/GPU/ports may change, and IDs must not
+        # become filesystem paths or collide after filename sanitization.
+        worker_id = str(worker_config["id"])
+        filename = hashlib.sha256(worker_id.encode("utf-8")).hexdigest() + ".db"
+        database_path = os.path.join(database_directory, filename).replace(os.sep, "/")
+        # Use the same URL codec as ComfyUI; raw '?' and '%xx' can otherwise
+        # truncate/decode the path and make distinct workers share a database.
+        from sqlalchemy.engine import URL, make_url
+        database_url = URL.create("sqlite", database=database_path).render_as_string()
+        if make_url(database_url).database != database_path:
+            raise ValueError(
+                "Installed SQLAlchemy cannot safely encode the worker database path; "
+                "use a user directory without '?' or an explicit --database-url with a safe path"
+            )
+        os.makedirs(database_directory, exist_ok=True)
+        cmd.extend(["--database-url", database_url])
+
    def build_launch_command(self, worker_config, comfy_root):
        """Build the command to launch a worker."""
        main_py = os.path.join(comfy_root, "main.py")
@@ -39,10 +141,19 @@ class LaunchCommandBuilder:
            cmd = [
                get_python_executable(),
                main_py,
-                "--port",
-                str(worker_config["port"]),
-                "--enable-cors-header",
            ]
+            cmd.extend(self._build_runtime_launch_args())
+            cmd.extend(["--port", str(worker_config["port"])])
+
+            current_args = self._get_runtime_args()
+            current_cors = getattr(current_args, "enable_cors_header", None) if current_args else None
+            cmd.append("--enable-cors-header")
+            if current_cors is not None:
+                cmd.append(str(current_cors))
+
+            if "--disable-auto-launch" not in cmd:
+                cmd.append("--disable-auto-launch")
+
            debug_log(f"Using main.py: {main_py}")
        else:
            error_msg = f"Could not find main.py in {comfy_root}\n"
@@ -76,4 +187,7 @@ class LaunchCommandBuilder:
                        raise ValueError(f"Invalid characters in extra_args: {arg}. Forbidden: {forbidden}")
                cmd.extend(extra_args_list)

+        if int(self._arg_value(cmd, "--port")) != int(worker_config["port"]):
+            raise ValueError("extra_args must not override the configured worker port; set the port in the UI/config instead")
+        self._add_worker_database(cmd, worker_config, comfy_root)
        return cmd
@@ -7,7 +7,9 @@ import time
 from ...utils.config import load_config, save_config
 from ...utils.constants import PROCESS_TERMINATION_TIMEOUT, PROCESS_WAIT_TIMEOUT, WORKER_CHECK_INTERVAL
 from ...utils.logging import debug_log, log
+from ...utils.network import get_server_port
 from ...utils.process import get_python_executable, is_process_alive, terminate_process
+from ..ports import validate_worker_port

 try:
    import psutil
@@ -28,11 +30,23 @@ class ProcessLifecycle:
        """Launch a worker process with logging."""
        _ = show_window  # Kept for API compatibility.
        comfy_root = self._manager.find_comfy_root()
+        config = load_config()
+        try:
+            master_port = get_server_port()
+        except AttributeError:
+            master_port = None
+        if master_port is None:
+            # The auto-launch timer can fire during custom-node imports, before
+            # PromptServer assigns its port. Still reserve the configured port.
+            from comfy.cli_args import args
+            master_port = args.port
+        validate_worker_port(worker_config, master_port, config.get("workers", []))

        env = os.environ.copy()
        env["CUDA_VISIBLE_DEVICES"] = str(worker_config.get("cuda_device", 0))
        env["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"
        env["COMFYUI_MASTER_PID"] = str(os.getpid())
+        env["COMFYUI_IS_WORKER"] = "1"

        cmd = self._manager.build_launch_command(worker_config, comfy_root)
        cwd = comfy_root
@@ -1,4 +1,5 @@
 import os
+import sys

 from ...utils.logging import debug_log, log

@@ -6,6 +7,21 @@ from ...utils.logging import debug_log, log
 class ComfyRootDiscovery:
    """Resolve the ComfyUI root directory across local and container layouts."""

+    def _find_root_from_loaded_modules(self):
+        """Use already-imported ComfyUI modules to locate the runtime root."""
+        for module_name in ("server", "folder_paths", "main"):
+            module = sys.modules.get(module_name)
+            module_file = getattr(module, "__file__", None)
+            if not module_file:
+                continue
+
+            candidate = os.path.dirname(os.path.abspath(module_file))
+            if os.path.exists(os.path.join(candidate, "main.py")):
+                debug_log(f"Found ComfyUI root via loaded module {module_name}: {candidate}")
+                return candidate
+
+        return None
+
    def find_comfy_root(self):
        # Start from current file location.
        current_dir = os.path.dirname(os.path.abspath(__file__))
@@ -17,12 +33,17 @@ class ComfyRootDiscovery:
            debug_log(f"Found ComfyUI root via COMFYUI_ROOT environment variable: {env_root}")
            return env_root

-        # Method 2: Try going up from custom_nodes directory.
+        # Method 2: Inspect the already-loaded ComfyUI runtime modules.
+        runtime_root = self._find_root_from_loaded_modules()
+        if runtime_root:
+            return runtime_root
+
+        # Method 3: Try going up from custom_nodes directory.
        if os.path.exists(os.path.join(potential_root, "main.py")):
            debug_log(f"Found ComfyUI root via directory traversal: {potential_root}")
            return potential_root

-        # Method 3: Look for common Docker paths.
+        # Method 4: Look for common Docker paths.
        docker_paths = [
            "/basedir",
            "/ComfyUI",
@@ -37,7 +58,7 @@ class ComfyRootDiscovery:
                debug_log(f"Found ComfyUI root in Docker path: {path}")
                return path

-        # Method 4: Search upwards for main.py.
+        # Method 5: Search upwards for main.py.
        search_dir = current_dir
        for _ in range(5):
            if os.path.exists(os.path.join(search_dir, "main.py")):
@@ -48,7 +69,7 @@ class ComfyRootDiscovery:
                break
            search_dir = parent

-        # Method 5: Try to import and use folder_paths.
+        # Method 6: Try to import and use folder_paths.
        try:
            import folder_paths

@@ -814,7 +814,7 @@
      "outputs": [],
      "properties": {},
      "widgets_values": [
-        "If all your GPUs are the same/similar, set static_distribution to true\n"
+        "Workers pull tiles from a shared queue, so faster workers can process more tiles automatically.\n"
      ],
      "color": "#432",
      "bgcolor": "#653"
Author	SHA1	Message	Date
Robert Wojciechowski	9345a8e71b	docs: link community add-ons and forks	2026-10-12 01:20:46 +00:00
Robert Wojciechowski	a630f55bd9	docs: move compressed result transfer guide out of README	2026-10-11 20:55:37 +00:00
ymiyad Claude Opus 5.5 ymiyad	6edd3fda38	feat(collector): optional compressed worker → master result transfer (#97 ) * feat(collector): compressed worker -> master result transfer Workers sent every frame as an uncompressed PNG (compress_level=0), base64-encoded inside a JSON request, one request per frame. For cloud workers this makes result download (egress) the dominant transfer cost: a 121-frame 720p batch is ~446 MB per worker. Add `transfer_format` / `transfer_quality` optional widgets to Distributed Collector: - legacy_png (default): unchanged behaviour - png, ffv1: lossless, bit-identical master tensors to legacy_png - jpeg, webp: lossy stills - h264, h265, av1: lossy video of the whole batch Compressed results are posted as multipart/form-data chunks (binary, no base64, ~32 MB soft cap per request, configurable with COMFYUI_DISTRIBUTED_TRANSFER_CHUNK_BYTES). The master decodes each chunk off the event loop and enqueues one item per frame, so collection, ordering and audio handling are unchanged. Encoding also runs in an executor on the worker. Compatibility: - /distributed/job_complete still accepts the legacy JSON envelope. - A worker talking to an older master gets a 400 on the first chunk and resends everything as legacy_png. - Missing video encoders fall back to h264 (lossy) or png (ffv1). Measured on 121 frames at 1280x720: png 163 MB (2.7x), ffv1 128 MB (3.5x), h264 q90 2.4 MB (186x, 40.2 dB), av1 q90 0.4 MB. Also clips IMAGE values before 8-bit quantization on the new path so out-of-range values no longer wrap around. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0166t8T3CVaxZkJbP2RtSpo6 * fix(collector): wire transfer options through V3 node; bound finalized payload size Addresses review on #97. V3 integration - Add optional `transfer_format` / `transfer_quality` inputs to the registered nodes/v3.py DistributedCollector schema (legacy defaults) and accept/forward them in execute() to the runtime helper. - tests/test_v3_collector_transfer.py checks the registered node's public schema and argument forwarding without a ComfyUI checkout; the opt-in real-runtime acceptance (tests/helpers/v3_runtime_check.py) now allows exactly these appended optional inputs, verifies their contract, and checks forwarding through the real executor. Payload size bound - encode_chunks() enforces limits on finalized bytes (after encoder flush and muxer finalization). Encoder lookahead kept the pre-flush buffer near zero, so a chunk could hold the whole batch and finalize far above the limit. Oversized video chunks are re-encoded with proportionally fewer frames; the next chunk is sized from observed bytes/frame. - Multi-frame chunks stay within TRANSFER_MAX_CHUNK_BYTES (32 MiB); a single frame may use up to TRANSFER_MAX_REQUEST_BYTES (96 MiB, new, COMFYUI_DISTRIBUTED_TRANSFER_MAX_REQUEST_BYTES) minus envelope reserve. A frame that cannot fit raises FrameTooLargeError. - The worker encodes all chunks before sending, so an unfittable frame fails before anything is delivered (no partial batch on the master). - Audio rides on the last chunk only when the request stays in bounds; otherwise it is sent as a final audio-only completion. - Legacy fallback triggers only on an older master's rejection ("Invalid JSON payload"); other errors, e.g. size limits, raise with a pointer to the limit settings instead of resending as legacy_png. - The master returns 413 when a request exceeds --max-upload-size. Tests: codec flush-overshoot and single-frame cases, worker fallback / nothing-sent / audio placement, and real aiohttp server tests with client_max_size covering bounded high-entropy video, 413 reporting, and unfittable frames. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0166t8T3CVaxZkJbP2RtSpo6 --------- Co-authored-by: ymiyad <ymiyad@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-11 20:50:23 +00:00
Robert Wojciechowski	6f85129e45	Bump version from 1.4.7 to 1.5.0	2026-10-11 10:06:41 +11:00
Robert Wojciechowski	a53d88f7fb	test: remove redundant coverage and consolidate happy paths (#95 )	2026-10-10 16:00:41 -07:00
Robert Wojciechowski	9be342f5fb	feat: migrate distributed nodes to native ComfyUI V3 API (#94 ) * feat: migrate distributed nodes to native ComfyUI V3 API * fix: hide Distributed Value backing fields in Nodes 2.0 Use native widget visibility without converting backing fields into sockets. Preserve widget types, serializers and options identity; cover edits, reload, worker refresh and linked widgets.	2026-10-10 16:00:36 -07:00
Robert Wojciechowski	a1faf7e916	fix: isolate local worker databases and avoid port conflicts (#93 ) * fix: isolate local worker databases and avoid port conflicts * fix: harden local worker startup preflight and database paths Handle auto-launch before the master binds, allow TIME_WAIT restarts without accepting active listeners, resolve relative paths in the worker cwd, and round-trip SQLite URLs through SQLAlchemy. Add regressions and remove the README additions.	2026-10-10 16:00:31 -07:00
Robert Wojciechowski	32ac027e0e	docs: align selected copy with current behavior	2026-07-12 11:13:22 +00:00
Robert Wojciechowski	fec959e1ac	chore: bump version to 1.4.7	2026-07-12 10:40:27 +00:00
Robert Wojciechowski	cedc8d4591	feat: support audio-only distributed workflows (#87 ) Support image, audio, or combined distributed collection with guarded audio-only worker, master, endpoint, preview, and delegate-only paths.	2026-07-12 20:36:43 +10:00
Robert Wojciechowski	db01824d6e	Update pyproject.toml	2026-06-06 09:10:43 +10:00
Robert Wojciechowski	6e7818bee6	fix: preserve delegate-only master config inputs (#86 ) Fixes #85	2026-06-05 17:12:25 +10:00
Robert Wojciechowski	c246d965e7	Update pyproject.toml	2026-05-28 09:00:17 +10:00
Robert Wojciechowski	d6ce26f143	Merge pull request #84 from robertvoy/fix/issue-83 Fix collector handling of ComfyUI list inputs	2026-05-28 08:59:02 +10:00
Robert Wojciechowski	e2125c7529	Fix collector handling of ComfyUI list inputs	2026-05-26 23:02:26 +00:00
Robert Wojciechowski	a91f9fb081	Update pyproject.toml	2026-04-08 10:01:49 +10:00
Robert Wojciechowski	6874d2735f	Merge branch 'fix/issue-78-queue-status'	2026-04-07 23:41:58 +00:00
Robert Wojciechowski	0e9ee7fbac	test: make async helper regression portable	2026-04-07 23:39:18 +00:00
Robert Wojciechowski	5386de10e3	fix: include queue metadata timestamps	2026-04-07 23:34:15 +00:00
Robert Wojciechowski	41f9e44945	fix: return native prompt queue metadata	2026-04-07 23:19:37 +00:00
Robert Wojciechowski	7792d613bb	Update FUNDING.yml	2026-04-04 17:42:09 +11:00
Robert Wojciechowski	6e698512b7	Update pyproject.toml	2026-04-04 17:36:24 +11:00
Robert Wojciechowski	79cc9f5ad5	Update registry publish action ref	2026-04-04 06:35:44 +00:00
Robert Wojciechowski	4eba87cba3	Update pyproject.toml	2026-04-04 17:09:55 +11:00
Robert Wojciechowski	27e08de94c	Document ComfyUI Desktop support	2026-04-04 06:06:59 +00:00
Robert Wojciechowski	c8453a139b	Use loopback callback URLs for local workers	2026-04-04 00:15:00 +00:00
Robert Wojciechowski	aae831e1e5	Fix stale master callback port selection	2026-04-04 00:05:49 +00:00
Robert Wojciechowski	e7ab67733b	Add ComfyUI Desktop worker support	2026-04-03 21:54:51 +00:00
Robert Wojciechowski	dd55ff740e	fix: forward all queuePrompt args through interceptor The interceptor only captured (number, prompt) and dropped the third options argument. This caused partialExecutionTargets to be lost, making ComfyUI execute all output nodes instead of just the selected one when using Execute Selected Output. Fixes #76	2026-03-26 22:00:53 +00:00
Robert Wojciechowski	a6d0b82d35	Update README.md	2026-03-02 16:10:42 +11:00
Robert Wojciechowski	a694272b40	Harden worker probe response validation and add tests	2026-03-01 22:36:57 +00:00
Robert Wojciechowski	16ea22a643	Update pyproject.toml	2026-02-28 15:58:46 +11:00
Robert Wojciechowski	071d1c1d93	Update pyproject.toml	2026-02-28 04:53:20 +00:00
				`@@ -0,0 +1 @@`
				`"""Internal extension lifecycle support (not a node provider)."""`