Skip to content

Make videos on the computer you already own. FreeVideo runs MiniMax H3 in as little as 8 GB of VRAM and 16 GB of RAM, and adapts its acceleration path to your hardware.

82.5 KB
Raw Blame
"""One local FP8 request, reusing the native ComfyUI encoder in a separate child.

Use a saved profile or select placement from current available resources.
The parent imports no tensor runtime. Standalone requests use fresh workers;
ComfyUI can reuse an isolated worker and reclaim its idle models. Both paths
share the exclusive GPU-work lock and monitor the actual compute process.
"""
import argparse
import json
import os
import re
from pathlib import Path
import signal
import subprocess
import sys
import shutil
import time
from contextlib import nullcontext

from .locking import runtime_lock, LOCK_ENV
from .paths import vdn_root, comfy_root
from .monitoring import save
from .encoder_checkpoint import preflight_encoder
from .music_request import without_music
from . import tuning
from . import processes
from .system import (inference_headroom, inference_memory_sample, inference_environment, memory_sample,
                     windows, inference_pressure, inference_emergency_floor, ram_budget_is_estimate)
from .adaptive import (WorkerExit, classify_failure, local_identity, history_path,
                       attempt_geometry, execute_attempts, complete_observation, benchmark_allocator_limit)
from .resource_history import ResourceHistory


# A worker that exits after a CUDA error normally does so at once. One whose
# driver teardown never returns would otherwise hold the request forever, so
# the controller ends a worker that recorded this failure and is still running.
FAILED_WORKER_GRACE_SECONDS = 20.


class FailureReceipt:
    """Whether the worker's metrics file records a request ended by a CUDA error."""
    def __init__(self, command):
        self.path = self.stamp = None
        self.found = False
        self.since = time.time_ns()  # A receipt left by an earlier request is not this worker's.
        try:
            request = json.loads(Path(command[command.index('--request') + 1]).read_text(encoding='utf-8'))
            self.path = Path(request['metrics']) if request.get('metrics') else None
        except (ValueError, IndexError, KeyError, OSError, TypeError):
            pass

    def recorded(self):
        if self.path is None or self.found:
            return self.found
        try:
            status = self.path.stat()
            stamp = (status.st_mtime_ns, status.st_size)
            if stamp == self.stamp or status.st_mtime_ns < self.since:
                return False
            metrics = json.loads(self.path.read_text(encoding='utf-8'))
        except (OSError, ValueError):
            return False  # Unreadable or half written: read again at the next poll.
        self.stamp = stamp
        failure = metrics.get('failure') if isinstance(metrics, dict) else None
        self.found = (isinstance(failure, dict) and metrics.get('success') is False
                      and failure.get('kind') == 'cuda_error')
        return self.found


def child(command, env, descriptor, log, *, ram_budget_bytes=None, gpu=None, on_start=None,
          minimum_available_bytes=None, ram_budget_is_estimate=False):
    from .ram import ProcessMemory
    memory = ProcessMemory() if ram_budget_bytes is not None else None
    telemetry = {}
    monitor = None
    from .exit_diagnostics import exit_reading, memory_sample
    # A worker that the system ends cannot report its own memory: this process reads it.
    telemetry['memory_at_start'] = memory_sample()
    with log.open('w', encoding='utf-8') as stream:
        from .resident_process import ENV, RemoteProcess, SessionRestarted
        module = command[command.index('-m')+1] if '-m' in command else None
        process = None
        if env.get(ENV) and module in ('freevideo_engine.worker', 'freevideo_engine.encode_worker'):
            try:
                process = RemoteProcess(env[ENV], command, env, descriptor, log)
            except SessionRestarted as error:
                env = dict(env)
                env.pop(ENV, None)
                os.environ.pop(ENV, None)
                print(json.dumps({'event': 'resident_session_restart', 'reason': str(error)}), flush=True)
        if process is None:
            process = processes.popen(command, env=env, stdout=stream, stderr=subprocess.STDOUT,
                                       pass_fds=(descriptor,), start_new_session=True)
        pending_error = None
        receipt = FailureReceipt(command)
        failed_since = None
        try:
            if on_start:
                on_start(process.pid)
            if gpu:
                from .monitoring import Monitor
                monitor = Monitor(log.with_suffix('.gpu.csv'), device=gpu, pid=process.pid).start()
            while process.poll() is None:
                if memory:
                    sample = memory.sample(process.pid)
                    telemetry.setdefault('ram_start', sample)
                    telemetry['ram_last'] = sample
                    pressure = inference_pressure(sample, ram_budget_bytes, minimum_available_bytes,
                                                  budget_is_estimate=ram_budget_is_estimate)
                    telemetry['ram_guard'] = pressure
                    if pressure['reasons'] and not pressure['enforced_reasons']:
                        # Keep the first crossing even when later samples return
                        # below the estimate. Let the OS reclaim/page memory; do
                        # not trim another application's working set or alter its
                        # pagefile settings. One event per worker, not per sample.
                        if 'ram_budget_warning' not in telemetry:
                            telemetry['ram_budget_warning'] = dict(pressure)
                            print(json.dumps(dict(event='ram_budget_warning', **pressure)), flush=True)
                    if pressure['enforced_reasons']:
                        detail = ''
                        if pressure.get('commit_available_bytes') is not None:
                            if pressure.get('physical_available_bytes') is not None:
                                detail = ' Physical RAM available %.2f GiB;' % (pressure['physical_available_bytes']/2**30)
                            detail += ' Windows commit headroom %.3f GiB.' % (pressure['commit_available_bytes']/2**30)
                            if pressure['commit_available_bytes'] <= pressure['emergency_floor_bytes']:
                                detail += ' Windows commit headroom exhausted; this is separate from physical RAM usage.'
                        raise MemoryError(('RAM guard: %s. Working RAM %.2f GiB / budget %.2f GiB; '
                            'available physical/commit headroom %.2f GiB / emergency floor %.3f GiB.' %
                            (', '.join(pressure['enforced_reasons']), pressure['working_bytes']/2**30,
                             ram_budget_bytes/2**30, pressure['available_bytes']/2**30,
                             pressure['emergency_floor_bytes']/2**30)) + detail)
                if receipt.recorded():
                    failed_since = time.monotonic() if failed_since is None else failed_since
                    if time.monotonic() - failed_since >= FAILED_WORKER_GRACE_SECONDS:
                        telemetry['worker_unresponsive_after_failure_seconds'] = time.monotonic() - failed_since
                        telemetry['worker_exit'] = dict(exit_reading(None), memory=memory_sample())
                        print(json.dumps({'event': 'worker_ended_after_failure',
                                          'seconds': telemetry['worker_unresponsive_after_failure_seconds']}), flush=True)
                        raise WorkerExit(None, log)
                try:
                    process.wait(timeout=.5)
                except subprocess.TimeoutExpired:
                    pass
            code = process.returncode
            if code:
                telemetry['worker_exit'] = dict(exit_reading(code), memory=memory_sample())
                raise WorkerExit(code, log)
        except BaseException as error:
            pending_error = error
            try:
                processes.stop(process)
            except BaseException as stop_error:
                # A stop timeout is not a controlled timeout. The worker may
                # still own CUDA; never convert this into an ordinary retry.
                # A worker observed gone afterwards owns nothing, whatever the
                # signal call reported while it was exiting.
                if not processes.gone(process):
                    error.worker_stop_confirmed = False
                    error.worker_stop_error = repr(stop_error)
            error.telemetry = telemetry
            raise
        finally:
            cleanup_errors = []
            for name, observed, suffix in (('ram', memory, '.memory.json'), ('gpu', monitor, '.gpu.json')):
                if observed is not None:
                    try:
                        telemetry[name] = observed.result() if name == 'ram' else observed.stop()
                        save(log.with_suffix(suffix), telemetry[name])
                    except BaseException as error:
                        cleanup_errors.append(error)
            if cleanup_errors:
                if pending_error is None:
                    raise cleanup_errors[0]
                pending_error.cleanup_errors = [repr(error) for error in cleanup_errors]
    return telemetry


def main():
    from .cli import main as cli
    sys.argv.insert(1, 'generate')
    cli()


def suggest_alternatives(error, hardware, options):
    """Name smaller requests this GPU can run now, when only VRAM refused this one.

    A request with a new prompt is first planned for its text encoder, which
    already applies the video stage's VRAM floor, so that is where most
    refusals happen. Suggestions are planned for the video stage either way.
    """
    if error.details.get('insufficient') != ['gpu'] or not options.get('canvas'):
        return
    from .policy import describe_alternatives, feasible_alternatives
    try:
        rows = feasible_alternatives(hardware, options['canvas'],
                                     **{key: value for key, value in options.items() if key not in ('canvas', 'stage')})
    except Exception:  # A suggestion is advisory; the refusal stands as planned.
        return
    if rows:
        error.details['alternatives'] = rows
        error.args = (str(error) + '\n' + describe_alternatives(rows),)


def low_memory_mode(engine):
    """The placements that trade speed for a smaller GPU working set, if this plan uses them."""
    if engine.get('residual_offload') or engine.get('attention_cpu_outputs'):
        return dict(staging=bool(engine.get('residual_offload')), host_outputs=bool(engine.get('attention_cpu_outputs')))
    return None


def automatic_profile(args, canvas, *, stage, evidence, descriptor=None, environment=None):
    """Plan with idle-cache accounting; reclaim once if it prevents admission."""
    from .hardware import detect
    from .policy import choose, ResourceBudgetError
    from .kernel_capabilities import available_backends
    from .resident_process import credit, release_idle_cache, ENV, SessionRestarted
    environment = os.environ if environment is None else environment
    for attempt in range(2):
        raw = detect()
        encoding_stage = stage == 'before-encoding' and bool(getattr(args, 'prompt_file', None))
        hardware, state = credit(raw, environment, reuse_encoder=encoding_stage)
        row = dict(stage=stage, raw=raw.to_dict(), adjusted=hardware.to_dict(), idle_cache=state)
        from .system import system_memory
        try:
            row['system_memory'] = system_memory()
        except (OSError, RuntimeError):
            pass
        evidence.append(row)
        try:
            # What this machine has demonstrably held, for the weight cache
            # only. None on a first run, which leaves the plan unchanged.
            from .adaptive import demonstrated_local_ram
            options = {key: getattr(args, key) for key in
                ('vram_gib', 'ram_gib', 'attention', 'gpu_reserve_gib', 'ram_reserve_gib')}
            planning_canvas = dict(canvas)
            if getattr(args, 'task', None):
                planning_canvas['task'] = args.task
            if getattr(args, 'step_cache', None):
                # The planner keeps the first-block cache only where it fits.
                planning_canvas['step_cache'] = args.step_cache
            kernels = {}
            offered = available_backends(hardware, probe_missing=False, evidence=kernels)
            row['attention_backends'] = dict(kernels, offered=sorted(offered))
            options.update(available_backends=offered, canvas=planning_canvas,
                demonstrated_ram_bytes=demonstrated_local_ram(hardware, args, canvas))
            cache = getattr(args, 'cache', None)
            if cache is not None and (Path(cache) / 'manifest.json').is_file():
                manifest = json.loads((Path(cache) / 'manifest.json').read_text(encoding='utf-8'))
                options['precision'] = 'int8' if manifest.get('precision') == 'int8' else 'fp8'
            if getattr(args, '_lora_max_block_bytes', 0):
                options['lora_max_block_bytes'] = args._lora_max_block_bytes
            if getattr(args, '_lora_root_bytes', 0):
                options['lora_root_bytes'] = args._lora_root_bytes
            if encoding_stage:
                options['stage'] = 'encoding'
            try:
                selected = choose(hardware, **options)
            except ResourceBudgetError as estimate:
                details = estimate.details
                cache_cannot_resolve = (attempt or not state or not environment.get(ENV) or
                    details['gpu_capacity_bytes'] - details['gpu_reserve_bytes'] < details['gpu_minimum_bytes'])
                if (details['insufficient'] != ['gpu'] or details.get('gpu_requirement') != 'estimated_working_set'
                        or not cache_cannot_resolve):
                    raise
                selected = choose(hardware, **options, allow_capacity_trial=True)
                row.update(capacity_trial=True, resource_error=details)
            row['status'] = 'admitted'
            profile = selected.legacy_profile()
            if 'steps' in canvas:
                profile['engine']['steps'] = canvas['steps']
                profile['policy']['engine']['steps'] = canvas['steps']
            row['budget_bytes'] = dict(gpu=profile['gpu_budget_gb']*1e9, ram=profile['inference_ram_budget_gb']*1e9)
            row['reserve_bytes'] = dict(gpu=profile.get('policy', {}).get('gpu_system_reserve_bytes'),
                                        ram=profile.get('policy', {}).get('ram_system_reserve_bytes'))
            # Encoding is finished. Do not keep its process if its retained
            # working set already leaves less than the model loader's existing
            # 2 GiB increment inside the new whole-process RAM budget. Release
            # under the lease, then actually measure recovered commit/physical
            # capacity; never invent commit credit for GPU or mapped weights.
            memory = (state.get('memory') or {}) if state else {}
            used = memory.get('guard_bytes')
            mapped = memory.get('reclaimable_mapped_bytes')
            commit = memory.get('system_commit_available_bytes')
            # A read-only text-encoder checkpoint is cheap in the working-set
            # guard, but Windows still charges its section view to Commit until
            # the resident worker exits.  The old test only looked at
            # ``guard_bytes`` and therefore retained a 14--16 GiB mapping on a
            # 30 GiB machine: the next stage then had a 5.5 GiB budget and
            # reopened roughly 20 GiB of transformer weights on every step.
            # Releasing the idle worker is safe after conditioning is saved and
            # is preferable to letting Commit fall through the emergency floor.
            # Require both measurements so a missing/incomplete Windows sample
            # never causes a speculative restart.  On machines with genuine
            # commit headroom the resident encoder remains reusable.
            # Only Windows section views consume Commit while looking small in
            # the working-set guard.  Linux mappings are already represented by
            # MemAvailable/cgroup accounting and must not trigger a Windows
            # style encoder restart.
            mapped_commit_pressure = (
                hardware.system == 'Windows' and
                type(mapped) is int and mapped >= 4 * 2**30 and
                type(commit) is int and commit >= 0 and
                commit < mapped + 2 * 2**30)
            encoder_idle = state and any(m.get('role') == 'encoder' for m in state.get('models', []))
            # The plan counted the idle encoder's memory as reclaimable. If it
            # still streams every transformer block from disk with nothing
            # retained, actually reclaim it: a 16 GiB RTX 3060 Laptop kept the
            # encoder's 4.5 GiB while each step reread 21.6 GB of weights with
            # no room left for host read-ahead. Machines that retain weights
            # keep the encoder for the next prompt.
            from .policy import BLOCK_BYTES
            engine = profile['engine']
            before, after = getattr(raw, 'ram_available', None), getattr(hardware, 'ram_available', None)
            credited = after - before if type(before) is int and type(after) is int else 0
            retention_starved = (engine.get('stream_weights') is True and credited >= 2 * 2**30
                                 and engine.get('pin_host_gb', 0.) * 1e9 < BLOCK_BYTES)
            # The plan also counted the idle worker's GPU memory as free, but
            # only a process exit is sure to return memory the model bank does
            # not own. On a 6 GiB RTX 3060 Laptop the lowvram encoder's
            # streaming buffers held 0.80 GiB allocated (1.68 GiB reserved),
            # evicting the encoder released nothing, and the transformer,
            # planned with zero resident blocks, ran out of memory in its second
            # pass. The worker now frees those buffers after encoding; this
            # covers anything else it still holds.
            idle_gpu = state.get('reclaimable_gpu_bytes') if state else None
            gpu_starved = (type(idle_gpu) is int and idle_gpu >= 256 * 2**20
                           and engine.get('resident_blocks', 0) == 0)
            working_set_short = type(used) is int and used >= 0 and used + 2*2**30 > row['budget_bytes']['ram']
            reclaim = (stage == 'after-encoding' and not attempt and encoder_idle and environment.get(ENV)
                       and (working_set_short or mapped_commit_pressure or retention_starved or gpu_starved))
            if not reclaim:
                return hardware, state, profile
            reason = ('Idle encoder working set leaves insufficient model-loading room' if working_set_short
                      else 'Idle encoder mapping leaves insufficient Windows Commit headroom' if mapped_commit_pressure
                      else 'Idle encoder GPU memory leaves the transformer no spare VRAM' if gpu_starved
                      else 'Idle encoder memory leaves the transformer rereading every weight from disk')
            row.update(status='reclaim-before-load', reason=reason,
                       mapped_bytes=mapped if type(mapped) is int else None,
                       commit_available_bytes=commit if type(commit) is int else None)
        except ResourceBudgetError as error:
            from .exit_diagnostics import own_memory
            own = dict(own_memory())
            resident = ((state or {}).get('memory') or {})
            if (resident.get('guard_metric') == 'tree private working set'
                    and type(resident.get('guard_bytes')) is int and resident['guard_bytes'] >= 0):
                own['resident_private_working_set_bytes'] = resident['guard_bytes']
            if own:
                error.add_own_memory(own)
                row['own_memory'] = own
            row.update(status='rejected', resource_error=error.details)
            error.resource_planning = evidence
            impossible_capacity = any(error.details[name+'_capacity_bytes'] - error.details[name+'_reserve_bytes']
                                      < error.details[name+'_minimum_bytes'] for name in error.details['insufficient'])
            if attempt or impossible_capacity or not state or not environment.get(ENV):
                suggest_alternatives(error, hardware, options)
                raise
        print(json.dumps(dict(event='release_idle_cache', stage=stage,
            reason='Cached models prevent next-stage loading; releasing them and measuring again',
            resources=row.get('resource_error', row.get('budget_bytes')))), flush=True)
        lease_scope = runtime_lock() if descriptor is None else nullcontext(descriptor)
        with lease_scope as lease:
            try:
                row['recovery'] = release_idle_cache(environment, lease)
            except SessionRestarted:
                row['recovery'] = dict(released=True, reason='Old worker already confirmed stopped')
        environment.pop(ENV, None)
        os.environ.pop(ENV, None)


def _runtime_libraries(error, record):
    """Check the cuDNN files when this process saw them refused, or when the
    hardware probe, which imports torch, failed. Workers check their own failures."""
    try:
        from .runtime_libraries import mismatch, diagnose
        if mismatch(error) or getattr(error, 'torch_probe_failed', False):
            record['runtime_libraries'] = diagnose()
    except Exception:
        pass


def encoder_size_mismatch(encoding):
    # Cache hits retain the checkpoint with the original request's metrics.
    checkpoint = encoding.get('checkpoint') or (encoding.get('cache_source_metrics') or {}).get('checkpoint') or {}
    return checkpoint.get('tested_size') is False


def run(args):
    """Also retain admission/import failures before the main request starts."""
    output = Path(args.out).expanduser().resolve()
    preexisting = any(path.exists() for path in (output, output.with_suffix('.request.json'),
                                               output.with_suffix('.debug.json'), output.with_suffix('.artifacts')))
    started = time.perf_counter()
    try:
        return _run(args)
    except BaseException as error:
        if not preexisting and not getattr(error, 'diagnostic_recorded', False):
            from .diagnostic_resources import exception_details
            from .support_report import write as write_debug, code_identity
            planning = getattr(error, 'resource_planning', [])
            record = dict(success=False, request_seconds=time.perf_counter()-started,
                phase=planning[-1]['stage'] if planning else 'preflight', resource_planning=planning,
                error_type=type(error).__name__, exception=exception_details(error),
                error_message=str(error), resource_error=getattr(error, 'details', None), runtime_code=code_identity())
            if getattr(error, 'code', None):
                record['error_code'] = error.code
            _runtime_libraries(error, record)
            try:
                save(output.with_suffix('.request.json'), record)
                write_debug(output, record)
            except (OSError, ValueError):
                pass
        raise


def upscale_factor(args):
    """The two-pass upscale factor a command asked for: 2 (the original half-size first pass) unless given."""
    factor = getattr(args, 'upscale_factor', None)
    return 2 if factor in (None, 2) else factor


def dialogue_reason(prompt):
    """Shared eligibility for opening-voice references and hidden dialogue tails."""
    from .prompt_vlm.rules import split_source
    if not prompt or not split_source(prompt)[2]:
        return 'no_lines'
    if re.search(r'(?i)\b(?:sing|sings|singing|sang|sung|lyrics)\b|唱', prompt):
        return 'singing'
    return None


def hide_tail_geometry(canvas, prompt, requested=False, *, preview=False, max_frames=None):
    """Plan the generated canvas while keeping the ordinary output duration."""
    if not requested:
        return canvas, None
    from .continuation import HIDE_TAIL_FRAMES
    from .geometry import geometry
    # The product's longest selectable request is 60 seconds on the H3 grid.
    limit = geometry(seconds=60)['frames'] if max_frames is None else max_frames
    reason = 'preview' if preview else dialogue_reason(prompt)
    if reason is None and canvas['frames'] + HIDE_TAIL_FRAMES > limit:
        reason = 'too_long'
    if reason is not None:
        return canvas, dict(requested=True, used=False, reason=reason)
    generated = dict(canvas, **geometry(canvas['width'], canvas['height'], frames=canvas['frames'] + HIDE_TAIL_FRAMES))
    return generated, dict(requested=True, used=True, frames=HIDE_TAIL_FRAMES)


def _run(args):
    from .hardware import detect
    from .geometry import geometry
    from .continuation import (validate_frames, validate_route, prepare as prepare_continuation,
                               summary as continuation_summary, validate_snapshot, persist_snapshot, restore_snapshot,
                               audio_context, MISSING as CONTINUATION_MISSING)
    from .continuation_tail import pending as encoded_continuation, freeze as freeze_tail
    continuation_directory = continuation_first = None

    def freeze_continuation(value):
        from .paths import base_path
        return freeze_tail(value, canvas, continuation_first, continuation_directory,
                           profile['engine'].get('base') or base_path())

    def usable_continuation(value, *check):
        """The stored context when it fits this run, otherwise the previous video's own ending."""
        if 'tail' in value:
            return value
        try:
            return validate_snapshot(value, *check)
        except ValueError as error:
            if str(error) != CONTINUATION_MISSING:
                raise
        # A record of another version, other weights or another first-pass size.
        value = dict(encoded_continuation(continue_from, canvas),
                     **{key: value[key] for key in ('audio_context', 'source_video', 'anchor', 'pictures', 'sound', 'video_only')
                        if key in value})
        return freeze_continuation(value) if continuation_directory is not None else value

    frames = getattr(args, 'frames', None)
    continue_from = getattr(args, 'continue_from', None)
    continue_anchor = getattr(args, 'continue_anchor', None)
    if continue_anchor is not None and continue_from is None:
        raise ValueError('--continue-anchor requires --continue-from')
    # Every part of a long video is asked alike; only a part that continues another can use it.
    first_frame = None
    voice_reference = (dict(requested=True, used=False, reason=None)
                       if getattr(args, 'voice_reference', False) and continue_from is not None else None)
    if getattr(args, 'first_frame_reference', False) and continue_from is not None:
        if continue_anchor is not None:
            raise ValueError('Choose --first-frame-reference or --continue-anchor, not both')
        first_frame = dict(requested=True, used=False)
    from .media_request import read as read_media, task_for, cache_key
    from .original_audio import cli_media, prepare_request
    media = cli_media(args, read_media(getattr(args, 'media', None)))
    original_audio, original_canvas = prepare_request(media, getattr(args, 'width', 1344),
        getattr(args, 'height', 768), continuation=continue_from is not None)
    if continue_from is not None and frames is not None:
        validate_frames(frames)
    canvas = original_canvas or geometry(getattr(args, 'width', 1344), getattr(args, 'height', 768),
                      frames=frames, seconds=getattr(args, 'seconds', None))
    visible_canvas = canvas
    canvas, hide_tail = hide_tail_geometry(canvas,
        args.prompt_file.read_text(encoding='utf-8') if getattr(args, 'hide_tail', False) and args.prompt_file else None,
        getattr(args, 'hide_tail', False) and original_audio is None,
        preview=bool(getattr(args, 'preview', False) or getattr(args, 'refine_from', None)))
    if original_audio is not None and getattr(args, 'hide_tail', False):
        # The clip's samples set where the part ends; nothing is generated past them to hide.
        hide_tail = dict(requested=True, used=False, reason='original_audio')
    hide_tail_frames = hide_tail['frames'] if hide_tail and hide_tail['used'] else 0
    continuation = None
    from .two_pass import validate_steps
    requested_steps = getattr(args, 'base_steps', None)
    refine_steps = getattr(args, 'refine_steps', 3)
    two_pass = getattr(args, 'two_pass', True)
    preview = getattr(args, 'preview', False) is True
    from .preview import validate_flags, source as preview_source
    validate_flags(preview, getattr(args, 'refine_from', None), two_pass, requested_steps)
    refine_source = preview_source(args.refine_from) if getattr(args, 'refine_from', None) else None
    if requested_steps is not None:
        validate_steps(requested_steps, refine_steps, two_pass)
        if requested_steps != 8:
            canvas['steps'] = requested_steps
    if continue_anchor is not None:
        from .continuation import anchor_media
        media = anchor_media(media, continue_anchor)
    # The cast's pictures, sent with a continued part like with a part that starts fresh.
    # A clip used as is is the part's sound, not one of its pictures.
    pictures = []
    if continue_from is not None and continue_anchor is None and media.get('references'):
        from .continuation import continuation_pictures
        pictures = continuation_pictures(dict(media, references=[
            row for row in media['references'] if row.get('use') != 'original']))
    anchored = continue_anchor is not None or bool(pictures)
    # Too small to sample cleanly: render larger, scale the picture down. Decided before anything
    # compares or stores the canvas, so every later check sees the size that is sampled.
    from .two_pass import sampling_canvas
    canvas, output_size = sampling_canvas(canvas, staged=bool(preview or refine_source), media=media,
                                          conditioned=bool(args.conditioning))
    if continue_from is not None:
        validate_route(task=getattr(args, 'task', None) or ('ref2va' if anchored else 't2va'),
                       anchor=anchored, two_pass=two_pass,
                       preview=preview, refine_from=getattr(args, 'refine_from', None), media=media,
                       original_audio=original_audio is not None and 'segment' in original_audio)
        # Reject absent/mismatched context before text encoding or model loading.
        preview_encoded = False
        if refine_source:
            from .preview import continuation_snapshot
            snapshot, digest, preview_encoded = continuation_snapshot(refine_source, continue_from)
            continuation = restore_snapshot(snapshot, digest, canvas)
        elif getattr(args, 'continuation_snapshot', None):
            continuation = restore_snapshot(args.continuation_snapshot,
                getattr(args, 'continuation_snapshot_sha256', None), canvas)
        else:
            try:
                continuation = prepare_continuation(continue_from, canvas)
            except ValueError as error:
                if str(error) != CONTINUATION_MISSING:
                    raise
                # Nothing was stored for this file: its own ending is encoded when the run starts.
                continuation = encoded_continuation(continue_from, canvas)
        continuation = dict(continuation, audio_context=audio_context(), source_video=str(continue_from))
        if original_audio is not None:
            from .original_audio_chain import validate_continuation
            validate_continuation(original_audio, continuation)
            continuation.update(video_only=True, audio_context='clean')
        if first_frame is not None and original_audio is not None:
            # The clip used as is is the part's only audio row; no first-frame picture is added beside it.
            first_frame['reason'] = 'original_audio'
        elif first_frame is not None and pictures:
            # The cast's pictures already hold the people; the film's first frame is not added to them.
            first_frame['reason'] = 'pictures'
        elif first_frame is not None:
            from .continuation import anchor_media, chain_first_frame_picture
            try:
                # A context encoded from the file carries no first frame; whoever planned this run saw none either.
                kept = (None if 'tail' in continuation or preview_encoded
                        else chain_first_frame_picture(continuation, continue_from))
            except ValueError:
                kept = None
                first_frame['reason'] = 'unreadable'
            if kept is None:
                # Optional help: the part is made as an ordinary continuation and the report says why.
                first_frame.setdefault('reason', 'source_predates')
            else:
                if args.out.resolve().exists():
                    raise FileExistsError(args.out.resolve())
                args.out.resolve().parent.mkdir(parents=True, exist_ok=True)
                picture, picture_width, picture_height = kept
                # A second pass names the same picture its preview was made with.
                continue_anchor = None
                if refine_source:
                    from .preview import continuation_anchor
                    continue_anchor = continuation_anchor(refine_source)
                if continue_anchor is None:
                    continue_anchor = args.out.resolve().with_suffix('.first-frame.png')
                    continue_anchor.write_bytes(picture)
                media = anchor_media(media, continue_anchor)
                validate_route(task=getattr(args, 'task', None) or 'ref2va', anchor=True, two_pass=two_pass,
                               preview=preview, refine_from=getattr(args, 'refine_from', None), media=media)
                first_frame.update(used=True, width=picture_width, height=picture_height)
                anchored = True
        if anchored:
            continuation['anchor'] = media['references'][0]
        if pictures:
            continuation['pictures'] = len(pictures)
        if voice_reference is not None:
            if original_audio is not None:
                voice_reference['reason'] = 'original_audio'
            elif first_frame is not None and not pictures:
                voice_reference['reason'] = 'first_frame'
            elif continue_anchor is not None:
                voice_reference['reason'] = 'anchor'
            elif args.conditioning:
                # Preencoded conditioning cannot take another reference.
                voice_reference['reason'] = 'conditioning'
            else:
                voice_reference['reason'] = dialogue_reason(
                    args.prompt_file.read_text(encoding='utf-8') if args.prompt_file else None)
    active_loras = [row for row in media.get('loras', []) if row['strength'] != 0]
    if media:
        inferred_task = task_for(media)
        structural = any(media.get(k) for k in ('first', 'last', 'references', 'conditioning_info'))
        if structural and getattr(args, 'task', None) and args.task != inferred_task:
            raise ValueError('Explicit task disagrees with the media input')
        args.task = inferred_task if structural or not getattr(args, 'task', None) else args.task
        if args.conditioning and any(media.get(k) for k in ('first', 'last', 'references')):
            raise ValueError('Preencoded conditioning already includes media; use conditioning_info, not another set of files')
    base_cache = args.cache
    from .resident_process import credit
    planning = []
    if args.profile:
        hardware, resident_credit = credit(detect())
        profile = json.loads(args.profile.read_text(encoding='utf-8'))
    else:
        from .policy import ResourceBudgetError
        try:
            hardware, resident_credit, profile = automatic_profile(args, canvas, stage='before-encoding', evidence=planning)
        except ResourceBudgetError:
            if not hide_tail_frames:
                raise
            # The optional tail must fit this size/step tier too. Re-admit the
            # original duration before encoding anything; never shorten it.
            canvas, output_size = sampling_canvas(dict(canvas, **visible_canvas),
                staged=bool(preview or refine_source), media=media, conditioned=bool(args.conditioning))
            hardware, resident_credit, profile = automatic_profile(args, canvas, stage='before-encoding', evidence=planning)
            hide_tail, hide_tail_frames = dict(requested=True, used=False, reason='too_long'), 0
            if continuation is not None:
                from .continuation import OVERLAP_FRAMES
                continuation = dict(continuation, new_frames=canvas['frames'] - OVERLAP_FRAMES)
    print(json.dumps(dict(event='compute_device', backend='CUDA', name=getattr(hardware, 'gpu_name', None),
                          uuid=getattr(hardware, 'gpu_uuid', None), vram_total_bytes=getattr(hardware, 'vram_total', None),
                          vram_free_bytes=getattr(hardware, 'vram_free', None))), flush=True)
    allocator_limit_bytes = benchmark_allocator_limit(profile, getattr(args, 'allocator_limit_gib', None), hardware)
    if 'gpu_budget_bytes' in profile:
        profile = dict(gpu_budget_gb=profile['gpu_budget_bytes'] / 1e9,
                       inference_ram_budget_gb=profile['ram_budget_bytes'] / 1e9,
                       engine=profile['engine'], decoder=profile['decoder'],
                       allocator_config=profile['allocator_config'], policy=profile)
    base_steps = requested_steps if requested_steps is not None else profile['engine'].get('steps', 8)
    validate_steps(base_steps, refine_steps, two_pass)
    profile['engine']['steps'] = base_steps
    if args.profile and getattr(args, 'step_cache', None):
        profile['engine']['step_cache'] = args.step_cache
    if 'engine' in profile.get('policy', {}):
        profile['policy']['engine']['steps'] = base_steps
    if base_steps != 8:
        canvas['steps'] = base_steps
    if args.base:
        profile['engine']['base'] = str(args.base.resolve())
    if args.checkpoint:
        profile['engine']['checkpoint'] = str(args.checkpoint.resolve())
    if getattr(args, 'task', None):
        profile['engine']['task'] = args.task
    if allocator_limit_bytes is not None:
        profile['benchmark_allocator_limit_bytes'] = allocator_limit_bytes
    if args.out.suffix.lower() != '.mp4':
        raise ValueError('--out must name an MP4 file')
    manifest = json.loads((args.cache / 'manifest.json').read_text(encoding='utf-8'))
    if continuation is not None:
        from .two_pass import plan as continuation_plan
        validate_route(task=profile['engine'].get('task', 't2va'), anchor=anchored,
                       original_audio=original_audio is not None)
        planned = continuation_plan(canvas, two_pass, base_steps=base_steps, refine_steps=refine_steps,
                                    staged=bool(preview or refine_source), scale=upscale_factor(args))
        if two_pass and not planned['enabled'] and base_steps != 8:
            raise ValueError(planned['reason'] + ' A continuation needs two-pass generation.')
        continuation_first = planned['first']
        continuation = usable_continuation(continuation, canvas, None if active_loras else manifest, planned)
    if manifest.get('precision') not in ('fp8', 'int8', 'bf16'):  # BF16: the unquantized reference
        raise ValueError('Select the prepared official FP8 or int8 cache')
    destination = args.out.resolve()
    if destination.exists():
        raise FileExistsError(destination)
    destination.parent.mkdir(parents=True, exist_ok=True)
    artifacts = destination.with_suffix('.artifacts')
    artifacts.mkdir(exist_ok=False)
    continuation_directory = artifacts
    if continuation is not None and 'tail' in continuation:
        continuation = freeze_continuation(continuation)
    elif continuation is not None and 'snapshot' not in continuation:
        continuation = persist_snapshot(continuation, artifacts / 'continuation-source.safetensors')
    if args.prompt_file:
        shutil.copyfile(args.prompt_file, artifacts / 'prompt.txt')
    repo = Path(__file__).resolve().parents[1]
    report = {'profile': profile, 'seed': args.seed, 'success': False, 'geometry': canvas,
              **({'output_size': output_size} if output_size else {}),
              'resource_planning': planning,
              'artifacts': str(artifacts),
              'idle_resources': dict(automatic=not bool(args.profile), system=hardware.system,
                  vram_gib=getattr(args, 'vram_gib', None),
                  gpu_reserve_gib=getattr(args, 'gpu_reserve_gib', None),
                  allocator_limit_bytes=allocator_limit_bytes),
              'reclaimable_resident_models': resident_credit,
              'encoder_mode': 'native H3 encoder library child' if args.prompt_file else 'preencoded shared conditioning'}
    if continuation is not None:
        report['continuation'] = continuation_summary(continuation, hide_tail_frames=hide_tail_frames)
        if 'tail' in continuation:
            report['continuation']['context'] = 'encoded'
        report['audio_context'] = continuation['audio_context']
        if continue_anchor is not None:
            report['continue_anchor'] = continuation['anchor']
        if pictures:
            report['continue_pictures'] = len(pictures)
    if first_frame is not None:
        report['first_frame_reference'] = first_frame
    if voice_reference is not None:
        report['voice_reference'] = voice_reference
    if hide_tail is not None:
        report['hide_tail'] = hide_tail
    if hide_tail_frames:
        report['output_frames'] = (report['continuation']['new_frames'] if continuation is not None
                                   else canvas['frames'] - hide_tail_frames)
    from .support_report import code_identity, write as write_debug
    report['runtime_hardware'] = hardware.to_dict()
    from .device_index import card_report
    report['gpu_card'] = card_report(hardware)
    report['runtime_code'] = code_identity()
    started = time.perf_counter()
    applied = None
    def interrupted(signum, frame):
        raise KeyboardInterrupt(f'Request interrupted by signal {signum}')
    previous = processes.termination_handler(interrupted)
    try:
        with runtime_lock() as descriptor:
            if active_loras:
                lora_request = artifacts / 'lora-request.json'
                lora_result = artifacts / 'lora-result.json'
                save(lora_request, {'cache': str(args.cache.resolve()), 'adapters': active_loras, 'result': str(lora_result),
                    'mode': 'online' if profile['engine'].get('head_chunk') and profile['engine'].get('inference_kernels') else 'fused'})
                lora_env = dict(os.environ, PYTHONPATH=str(repo), CUDA_VISIBLE_DEVICES='', PYTHONUNBUFFERED='1')
                lora_env[LOCK_ENV] = str(descriptor)
                print(json.dumps({'event': 'lora_prepare_start'}), flush=True)
                report['lora_resources'] = child([sys.executable, '-m', 'freevideo_engine.lora_cache', '--request', str(lora_request)],
                    lora_env, descriptor, destination.with_suffix('.lora.log'),
                    ram_budget_bytes=profile['inference_ram_budget_gb'] * 1e9)
                prepared = json.loads(lora_result.read_text(encoding='utf-8'))
                args.cache = Path(prepared['cache'])
                report['lora'] = prepared['report']
                args._lora_max_block_bytes = prepared['report'].get('max_block_bytes', 0)
                args._lora_root_bytes = prepared['report'].get('root_bytes', 0)
                if continuation is not None:
                    continuation = usable_continuation(continuation, canvas,
                        json.loads((args.cache / 'manifest.json').read_text(encoding='utf-8')))
                    if 'tail' in continuation:
                        report['continuation']['context'] = 'encoded'
                if args._lora_max_block_bytes or args._lora_root_bytes:
                    profile.setdefault('policy', {})['lora_max_block_bytes'] = args._lora_max_block_bytes
                    profile['policy']['lora_root_bytes'] = args._lora_root_bytes
            if voice_reference is not None and voice_reference['reason'] is None:
                # Model identity, first-pass size and LoRA admission may have switched this
                # request to tail encoding. Decide only after those checks, before encoding media.
                if 'tail' in continuation:
                    voice_reference['reason'] = 'source_predates'
                else:
                    from .continuation import chain_first_sound, unpack_first_sound
                    try:
                        kept = chain_first_sound(continuation, continue_from)
                        sound = unpack_first_sound(kept) if kept is not None else None
                    except ValueError:
                        sound = None
                    if sound is None:
                        voice_reference['reason'] = 'unreadable'
                    else:
                        path = destination.with_suffix('.first-sound.wav')
                        path.write_bytes(sound)
                        from .media_request import digest
                        # After the cast's pictures: the sound is the last reference.
                        media = dict(media, version=1, references=[*media.get('references', []), dict(kind='audio',
                                     path=str(path), sha256=digest(path), bytes=path.stat().st_size)])
                        validate_route(task=getattr(args, 'task', None) or ('ref2va' if anchored else 't2va'), sound=True,
                                       anchor=anchored, two_pass=two_pass,
                                       preview=preview, refine_from=getattr(args, 'refine_from', None), media=media)
                        continuation['sound'] = media['references'][-1]
                        args.task = profile['engine']['task'] = task_for(media)
                        voice_reference['used'] = True
            resource_identity = local_identity(hardware, args.cache)
            history = ResourceHistory(history_path())
            history.recover_pending()
            report['resource_history'] = str(history.path)
            state = None
            input_cache = None
            report['tuning'] = {'profile_id': None, 'conditioning_cache_hit': False}
            report['input_cache'] = {'enabled': False, 'conditioning_hit': False}
            if not args.profile and not getattr(args, 'no_tuning', False):
                machine_path = tuning.state_path().parents[1] / 'machine.json'
                if machine_path.is_file():
                    try:
                        machine = json.loads(machine_path.read_text(encoding='utf-8'))
                        same_inputs = (base_cache.resolve() == Path(machine['cache']).resolve()
                            and args.encoder == machine['encoder']
                            and Path(args.comfy_python).absolute() == Path(machine['comfy_python']).absolute()
                            and (args.comfy_root or comfy_root()).resolve() == Path(machine['comfy_root']).resolve()
                            and args.model_paths and args.model_paths.resolve() == Path(machine['model_paths']).resolve())
                        if same_inputs:
                            # The text cache needs only the encoder and its code: no git, no video models.
                            from .input_cache import InputCache
                            input_cache = InputCache(tuning.text_identity(machine, hardware))
                            report['input_cache'].update(enabled=True, directory=str(input_cache.root))
                            identity = tuning.identity(machine, hardware)
                            state, reason = tuning.load_state(identity)
                            if active_loras:
                                state, reason = None, 'LoRA uses its own model history; encoder cache remains reusable'
                            report['tuning']['note'] = reason
                        else:
                            report['tuning']['note'] = 'Explicit model/encoder paths differ from the optimized installation'
                    except (OSError, ValueError, KeyError, subprocess.SubprocessError) as error:
                        report['tuning']['note'] = 'Could not validate saved tuning: ' + str(error)
            else:
                report['tuning']['note'] = 'Saved optimization bypassed by --no-tuning or --profile'
            if state:
                report['tuning']['baseline_report'] = state.get('baseline_report')
                report['tuning']['optimization_report'] = state.get('optimization_report')
            save(destination.with_suffix('.request.json'), report)
            temporary = artifacts
            allocator = profile.get('allocator_config', os.environ.get('PYTORCH_ALLOC_CONF',
                os.environ.get('PYTORCH_CUDA_ALLOC_CONF', 'backend:native,pinned_max_round_threshold_mb:128')))
            profile['allocator_config'] = allocator
            env = dict(os.environ, HF_HUB_OFFLINE='1', TRANSFORMERS_OFFLINE='1', PYTHONUNBUFFERED='1',
                       PYTORCH_ALLOC_CONF=allocator, PYTORCH_CUDA_ALLOC_CONF=allocator)
            env[LOCK_ENV] = str(descriptor)
            condition = temporary / 'conditioning.pt'
            if refine_source:
                # The preview's own conditioning: the exact file its first pass used.
                condition = Path(refine_source['conditioning'])
                if refine_source['report'].get('encoding'):
                    report['encoding'] = dict(refine_source['report']['encoding'], reused_from_preview=True)
                print(json.dumps({'event': 'conditioning_reused', 'source': 'preview'}), flush=True)
            elif args.conditioning:
                shutil.copyfile(args.conditioning, condition)
            if args.prompt_file and not refine_source:
                prompt_text = args.prompt_file.read_text(encoding='utf-8')
                # Checked before any cache lookup: a cached conditioning never stands in for the explicit permission.
                if not prompt_text.strip() and getattr(args, 'allow_empty_prompt', False) is not True:
                    raise ValueError('A nonempty prompt is required')
                if first_frame is not None and first_frame['used']:
                    # The saved prompt stays the user's own; the model is also told what the picture is.
                    from .continuation import first_frame_prompt
                    prompt_text = first_frame_prompt(prompt_text)
                prompt_text = without_music(prompt_text)
                encoding = {'prompt': prompt_text, 'encoder': args.encoder,
                            'comfy_root': str(args.comfy_root or comfy_root()),
                            'model_paths': str(args.model_paths.resolve()) if args.model_paths else None,
                            'output': str(condition), 'gpu_budget_gb': profile['gpu_budget_gb'],
                            'ram_budget_bytes': round(profile['inference_ram_budget_gb'] * 1e9),
                            'metrics': str(destination.with_suffix('.encoding.json')),
                            'diagnostic_output': str(destination)}
                if getattr(args, 'allow_empty_prompt', False):
                    encoding['allow_empty_prompt'] = True
                if media:
                    from .paths import base_path
                    encoding.update(media=media, geometry=canvas, base=profile['engine'].get('base') or str(base_path()),
                                    reference_latent_cache=str(input_cache.root.parent.parent) if input_cache else None)
                # Lets the encoder child read the video model while it computes, on a slow drive.
                from .model_read_ahead import request_fields
                if getattr(args, 'cache', None):
                    encoding.update(request_fields(args.cache, profile['engine'],
                                                   budget_is_estimate=ram_budget_is_estimate(args)))
                conditioning_key = cache_key(encoding['prompt'], media, canvas)
                encode_request = temporary / 'encode.json'
                encode_request.write_text(json.dumps(encoding) + '\n', encoding='utf-8')
                cached = input_cache.get(conditioning_key, condition) if input_cache else None
                if cached and encoder_size_mismatch(cached):
                    cached = None
                elif cached and (cached.get('success') is not True or cached.get('conditioning_shape', [])[1:] != [5120]):
                    condition.rename(condition.with_name('conditioning.cache-rejected-' + str(time.time_ns()) + '.pt'))
                    cached = None
                if not cached and state and task_for(media) == 't2va':
                    cached = tuning.cached_conditioning(state, encoding['prompt'], condition)
                    if cached and encoder_size_mismatch(cached):
                        cached = None
                if cached:
                    save(destination.with_suffix('.encoding.json'), cached)
                    destination.with_suffix('.encoding.log').write_text('Reused validated local text conditioning; encoder model was not loaded.\n', encoding='utf-8')
                    report['tuning']['conditioning_cache_hit'] = True
                    report['input_cache']['conditioning_hit'] = True
                    print(json.dumps({'event': 'conditioning_cache_hit'}), flush=True)
                    for trimmed in cached.get('reference_trims') or []:
                        print(json.dumps(dict(event='reference_trimmed', **trimmed)), flush=True)
                else:
                    try:
                        preflight_encoder(args.comfy_root or comfy_root(), args.encoder, encoding['model_paths'])
                    except Exception as error:
                        # Only a missing encoder stops the run; the worker stays the judge of anything else.
                        if str(error).startswith('ENCODER_MODEL_MISSING:'):
                            raise
                        print(json.dumps(dict(event='encoder_preflight_skipped', error=repr(error)[:300])), flush=True)
                    encoder_env = dict(env, PYTHONPATH=str(repo))
                    print(json.dumps({'event': 'encoding_start'}), flush=True)
                    encoder_attempt = history.begin(resource_identity, {'encoder': args.encoder},
                        attempt_geometry(canvas, profile['engine']), purpose='encoding',
                        evidence={'reason': 'Text conditioning cache miss',
                                  'request_artifacts': str(artifacts)})
                    report['encoding_attempt'] = encoder_attempt
                    save(destination.with_suffix('.request.json'), report)
                    try:
                        report['encoding_resources'] = child(
                            [args.comfy_python, '-m', 'freevideo_engine.encode_worker', '--request', str(encode_request)],
                            encoder_env, descriptor, destination.with_suffix('.encoding.log'),
                            ram_budget_bytes=profile['inference_ram_budget_gb'] * 1e9,
                            ram_budget_is_estimate=ram_budget_is_estimate(args),
                            minimum_available_bytes=inference_emergency_floor(profile['inference_ram_budget_gb'] * 1e9,
                                getattr(args, 'ram_reserve_gib', None)),
                            on_start=lambda pid: history.attach_worker(encoder_attempt, pid, phase='encoding'))
                        encoded = json.loads(destination.with_suffix('.encoding.json').read_text(encoding='utf-8'))
                        if encoded.get('success') is not True or not condition.is_file():
                            raise ValueError('Encoder exited without verified conditioning')
                    except BaseException as error:
                        try:
                            failed_encoding = json.loads(destination.with_suffix('.encoding.json').read_text(encoding='utf-8'))
                        except (OSError, ValueError):
                            failed_encoding = {}
                        failure = classify_failure(error, failed_encoding)
                        report['encoding_resources'] = getattr(error, 'telemetry', {})
                        report['encoding_failure'] = dict(phase=failed_encoding.get('phase', 'encoding'), failure=failure)
                        history.finish(encoder_attempt, failure['outcome'], details=failure)
                        raise
                    history.finish(encoder_attempt, 'success', details={'reason': 'Encoder exited with conditioning',
                        'encoding': encoded, 'resources': report.get('encoding_resources'),
                        'prompt_characters': len(encoding['prompt'])})
                report['encoding'] = json.loads(destination.with_suffix('.encoding.json').read_text(encoding='utf-8'))
                report['encoder_process_exited_before_video'] = not bool(os.environ.get('FREEVIDEO_RESIDENT_SESSION'))
                cacheable = not cached and not encoder_size_mismatch(report['encoding'])
                if input_cache and cacheable:
                    try:
                        report['input_cache']['conditioning_saved'] = input_cache.put(conditioning_key, condition, report['encoding'])
                        if input_cache.note:
                            report['input_cache']['note'] = input_cache.note
                    except (OSError, ValueError) as error:
                        report['input_cache']['note'] = str(error)
                if state and cacheable and task_for(media) == 't2va':
                    try:
                        tuning.remember_conditioning(state, encoding['prompt'], condition, report['encoding'])
                        tuning.save_state(state)
                    except (OSError, ValueError) as error:
                        report['tuning']['cache_note'] = str(error)
            # The encoder is done with the reference frames it normalized (over 1 GB per reference video).
            for frames in (temporary / 'media').glob('*.npy'):
                try:
                    frames.unlink(missing_ok=True)
                except OSError:
                    pass  # Windows keeps a file open; the next start's release frees it
            info = report.get('encoding', {}).get('conditioning_info') or media.get('conditioning_info')
            if info:
                if any(info.get(k) != canvas[k] for k in ('width', 'height', 'frames')):
                    raise ValueError('Encoded media does not match the requested geometry')
                for name in ('reference_video_tokens', 'reference_audio_tokens'):
                    count = info.get(name, 0)
                    if type(count) is not int or count < 0:
                        raise ValueError('Invalid reference token count')
                    canvas[name] = count
                if 'early_reference' in info:
                    canvas['early_reference'] = info['early_reference']
                profile['engine']['task'] = info['task']
                if original_audio is not None:
                    # Include all clean clock constants in live re-planning;
                    # the original track adds no reference audio rows.
                    args.task = info['task']
            if not condition.is_file():
                raise FileNotFoundError(condition)
            from .two_pass import plan as plan_sampling, ensure_checkpoint
            sampling_plan = plan_sampling(canvas, two_pass, profile['engine'].get('task', 't2va'),
                                          base_steps=base_steps, refine_steps=refine_steps,
                                          staged=bool(preview or refine_source), scale=upscale_factor(args))
            report['sampling_plan'] = sampling_plan
            if continuation is not None:
                validate_route(task=profile['engine'].get('task', 't2va'), anchor=anchored,
                               original_audio=original_audio is not None,
                               **(dict(sound=True, media=media) if voice_reference and voice_reference['used'] else {}))
                continuation = usable_continuation(continuation, canvas,
                    json.loads((args.cache / 'manifest.json').read_text(encoding='utf-8')), sampling_plan)
                if 'tail' in continuation:
                    report['continuation']['context'] = 'encoded'
            if preview:
                report['preview'] = dict(geometry=dict(sampling_plan['first'], fps=canvas['fps']))
            if refine_source:
                report['upscaled_preview'] = dict(output=refine_source['output'])
            if sampling_plan['enabled'] or sampling_plan['version'] == 2:
                canvas['sampling_plan'] = sampling_plan
            print(json.dumps(dict(event='sampling_plan', **sampling_plan, **({'preview': True} if preview else {}))), flush=True)
            save(destination.with_suffix('.request.json'), report)
            upscaler_checkpoint = None
            if sampling_plan.get('upscaler_sha256'):
                print(json.dumps(dict(event='latent_upscaler_prepare')), flush=True)
                upscaler_checkpoint = str(ensure_checkpoint())
            if not args.profile:
                # Encoding can take minutes; always recheck current free memory,
                # even before any optimization has been saved.
                hardware, resident_credit, live = automatic_profile(args, canvas, stage='after-encoding',
                    evidence=planning, descriptor=descriptor, environment=env)
                report['reclaimable_resident_models'] = resident_credit
                live['engine'].update({k: profile['engine'][k] for k in ('base', 'checkpoint', 'task', 'steps') if k in profile['engine']})
                profile = live
                report['profile'] = profile
                report['low_memory_mode'] = low_memory_mode(profile['engine'])
                if report['low_memory_mode']:
                    # Slower than usual but bounded; the panel says so while it runs.
                    print(json.dumps(dict(event='low_memory_mode', **report['low_memory_mode'])), flush=True)
            from .prediction import predict
            from .prediction_ui import show as show_prediction, errors as prediction_errors
            condition_hash = tuning.digest(condition)
            observations = history.observations(identity=resource_identity, limit=512, include_details=False)
            tokens = info.get('text_tokens') if info else report.get('encoding', {}).get('conditioning_shape', [None])[0]
            if tokens is None:
                tokens = next((row['observation'].get('text_tokens', row.get('geometry', {}).get('text_tokens'))
                    for row in reversed(observations)
                    if row['observation'].get('conditioning_sha256') == condition_hash), None)
            if state and args.attention == 'auto' and tokens is not None and sampling_plan['version'] in (1, 3):
                profile, applied = tuning.apply_profile(state, profile, canvas, tokens)
                report['profile'] = profile
                report['tuning']['profile_id'] = applied
            if allocator_limit_bytes is not None:
                profile['benchmark_allocator_limit_bytes'] = allocator_limit_bytes
            if not args.profile and not getattr(args, 'no_history_placement', False):
                from .prediction_policy import select
                profile, decision = select(profile, canvas, hardware, observations, resource_identity,
                                           text_tokens=tokens)
                report['history_placement'] = decision
                report['profile'] = profile
                from .adaptive import recovered_compute
                profile, report['recovered_compute'] = recovered_compute(profile, history, resource_identity, canvas)
                report['profile'] = profile
                if report['recovered_compute']['applied'] or report['recovered_compute'].get('reprobe'):
                    print(json.dumps(dict(event='recovered_compute', **report['recovered_compute'])), flush=True)
            from .compatibility import Store as CompatibilityStore, apply as apply_compatibility
            compatibility_state = CompatibilityStore(history.path.parent).status(resource_identity, persist=True)
            profile, report['compatibility'] = apply_compatibility(profile, compatibility_state)
            report['profile'] = profile
            if compatibility_state['level']:
                print(json.dumps(dict(event='compatibility', **report['compatibility'])), flush=True)
            def forecast(selected):
                if not args.profile and report.get('resource_attempts'):
                    # A failed resident worker may have exited and returned tens
                    # of GiB. Refresh limits in both directions; keep the chosen
                    # recovery options so a replan cannot undo offload/recompute.
                    _, _, live = automatic_profile(args, canvas,
                        stage='retry-%d' % (len(report['resource_attempts']) + 1), evidence=planning,
                        descriptor=descriptor, environment=engine_env)
                    for key in ('gpu_budget_gb', 'inference_ram_budget_gb'):
                        selected[key] = live[key]
                    if 'policy' in selected:
                        selected['policy'].update({k: v for k, v in live.get('policy', {}).items()
                                                  if k not in ('engine', 'decoder')})
                report['resource_prediction'] = predict(observations, resource_identity, selected, canvas, text_tokens=tokens)
                show_prediction(report['resource_prediction'])
            def validate(metrics, telemetry, selected):
                observation = complete_observation(metrics, canvas, destination, artifacts, telemetry)
                if observation is not None:
                    observation['conditioning_sha256'] = condition_hash
                    report['resource_prediction_error'] = prediction_errors(report['resource_prediction'], observation)
                return observation
            # A live policy may have replaced the initial profile after text
            # encoding. Record and execute that exact allocator consistently.
            allocator = profile.get('allocator_config', allocator)
            profile['allocator_config'] = allocator
            env.update(PYTORCH_ALLOC_CONF=allocator, PYTORCH_CUDA_ALLOC_CONF=allocator)
            save(destination.with_suffix('.request.json'), report)
            request = {'conditioning': str(condition), 'seed': args.seed, 'cache': str(args.cache.resolve()),
                       'input_cache_dir': str(input_cache.root.parent.parent) if input_cache else None,
                       'gpu_budget_bytes': round(profile['gpu_budget_gb'] * 1e9), 'engine_options': profile['engine'],
                       'decoder_options': profile['decoder'], 'output': str(destination),
                       'geometry': canvas, 'artifacts': str(artifacts),
                       **({'output_size': output_size} if output_size else {}),
                       'sampling_plan': sampling_plan, 'upscaler_checkpoint': upscaler_checkpoint,
                       'automatic_pass_cache': not bool(args.profile),
                       'metrics': str(destination.with_suffix('.engine.json'))}
            if continuation is not None:
                request['continuation'] = continuation
            if hide_tail_frames:
                request['hide_tail_frames'] = hide_tail_frames
            if original_audio is not None:
                request['original_audio'] = original_audio
                report['original_audio'] = original_audio
            if preview:
                request['preview'] = True
            if allocator_limit_bytes is not None:
                request['allocator_limit_bytes'] = allocator_limit_bytes
                report['benchmark_limit'] = {'pytorch_allocator_bytes': request['allocator_limit_bytes'],
                    'scope': 'PyTorch CUDA allocator only; other CUDA allocations and whole-device usage are measured separately.'}
            request_path = temporary / 'video.json'
            resume_decode = resume_refine = None
            # An upscale reuses its preview's first pass unless a later attempt
            # retains a newer checkpoint, or the current inputs no longer match.
            preview_pass = ({key: refine_source[key] for key in ('input', 'metrics', 'request')}
                            if refine_source else None)
            # Keep explicit dependency overlays while keeping the snapshotted engine first.
            engine_env = dict(env, PYTHONPATH=os.pathsep.join((str(repo), str(vdn_root()),
                                                              env.get('PYTHONPATH', ''))))
            def persist():
                save(destination.with_suffix('.request.json'), report)
            def launch(selected, attempt):
                nonlocal preview_pass
                selected_env = inference_environment(engine_env, selected['inference_ram_budget_gb'] * 1e9)
                if continuation is not None:
                    from .continuation import ADALN_TASK, ANCHOR_ADALN_TASK
                    selected['engine'] = dict(selected['engine'],
                        adaln_task=(selected['engine']['task'] if original_audio is not None
                                    else ANCHOR_ADALN_TASK if anchored else ADALN_TASK))
                request.update(engine_options=selected['engine'], decoder_options=selected['decoder'],
                               ram_budget_bytes=round(selected['inference_ram_budget_gb'] * 1e9),
                               ram_budget_is_estimate=ram_budget_is_estimate(args),
                               gpu_budget_bytes=round(selected['gpu_budget_gb'] * 1e9),
                               gpu_reserve_bytes=selected.get('policy', {}).get('gpu_system_reserve_bytes', 0),
                               capacity_trial=bool(selected.get('policy', {}).get('capacity_trial')),
                               resource_attempt=attempt)
                request.pop('first_pass_policy', None)
                request['automatic_pass_cache'] = not bool(args.profile) and len(report.get('resource_attempts', [])) <= 1
                # Explicit profiles and recovery placements retain their cap.
                # Automatic Windows requests can use a later driver-budget rise
                # without exceeding a user/benchmark capacity constraint.
                request['dynamic_gpu_budget'] = (hardware.system == 'Windows' and
                    request['automatic_pass_cache'] and getattr(args, 'gpu_reserve_gib', None) is None)
                request['gpu_capacity_bytes'] = min(hardware.vram_total,
                    int(args.vram_gib * 2**30) if args.vram_gib else hardware.vram_total)
                from .two_pass import clamp_first_pass_for_retry, first_pass_policy, keeps_first_pass_on_retry
                retry_keeps = (not args.profile and not request['automatic_pass_cache'] and keeps_first_pass_on_retry(
                    report.get('resource_attempts'), getattr(args, 'resource_retries', 2)))
                if request['automatic_pass_cache'] or retry_keeps:
                    first_policy = first_pass_policy(selected, canvas, sampling_plan)
                    if first_policy is not None:
                        first_policy['profile'], _ = apply_compatibility(first_policy['profile'], compatibility_state)
                        if retry_keeps:
                            # A recovery attempt narrows placement, not the first pass's arithmetic
                            # partitions: keep those and never exceed what the retry frees.
                            # With the pass cache off only the compute options (chunks, residual
                            # offload, prefetch, recompute) take effect; the rest is diagnostic.
                            first_policy, clamped = clamp_first_pass_for_retry(first_policy, selected)
                            first_policy['retry_clamped'] = clamped
                        request['first_pass_policy'] = first_policy
                        report['first_pass_policy'] = first_policy
                if resume_decode is not None:
                    request['resume_decode'] = dict(resume_decode)
                else:
                    request.pop('resume_decode', None)
                if resume_decode is None and resume_refine is not None:
                    request['resume_refine'] = dict(resume_refine)
                else:
                    request.pop('resume_refine', None)
                request.pop('resume_first_pass', None)
                if resume_decode is None and resume_refine is None and preview_pass is not None:
                    from .decode_resume import refine_provenance, same_identity
                    receipt = json.loads(Path(preview_pass['metrics']).read_text(encoding='utf-8'))
                    if same_identity(refine_provenance(request), receipt.get('refine_provenance')):
                        request['resume_first_pass'] = dict(preview_pass)
                        report['upscaled_preview']['first_pass_reused'] = True
                    else:
                        # Other models, settings or math: the preview's first pass
                        # is not this request's. Sample it again instead.
                        preview_pass = None
                        report['upscaled_preview'].update(first_pass_reused=False,
                            reason='The preview no longer matches the current models or settings; '
                                   'its first pass was sampled again.')
                        print(json.dumps(dict(event='preview_mismatch')), flush=True)
                save(request_path, request)
                # The epoch pairs with the worker's own events to time its start.
                print(json.dumps({'event': 'decode_resume' if resume_decode else 'video_start', 'resource_attempt': attempt,
                                  'engine': selected['engine'], 'decoder': selected['decoder'],
                                  'epoch': time.time()}), flush=True)
                try:
                    telemetry = child([sys.executable, '-m', 'freevideo_engine.worker', '--request', str(request_path)],
                        selected_env, descriptor, destination.with_suffix('.engine.log'),
                        ram_budget_bytes=selected['inference_ram_budget_gb'] * 1e9,
                        ram_budget_is_estimate=ram_budget_is_estimate(args),
                        minimum_available_bytes=inference_emergency_floor(selected['inference_ram_budget_gb'] * 1e9,
                            getattr(args, 'ram_reserve_gib', None)),
                        gpu=resource_identity['gpu']['uuid'],
                        on_start=lambda pid: history.attach_worker(attempt, pid, phase='video'))
                except BaseException as error:
                    try:
                        error.metrics = json.loads(destination.with_suffix('.engine.json').read_text(encoding='utf-8'))
                    except (OSError, ValueError):
                        pass
                    if isinstance(getattr(error, 'metrics', None), dict) and not error.metrics.get('sampling_memory'):
                        try:
                            from .diagnostics import read_bounded
                            raw, truncated = read_bounded(destination.with_suffix('.sampling-memory.json'), 2 * 2**20)
                            observed = json.loads(raw) if not truncated else None
                            if isinstance(observed, dict):
                                error.metrics['sampling_memory'] = observed
                        except (OSError, ValueError):
                            pass
                    raise
                return json.loads(destination.with_suffix('.engine.json').read_text(encoding='utf-8')), telemetry
            def archive(index, row):
                nonlocal resume_decode, resume_refine
                retained = artifacts / 'attempts' / ('%02d-%s' % (index + 1, row['id']))
                retained.mkdir(parents=True, exist_ok=False)
                paths = [destination] + [destination.with_suffix('.engine.' + ext)
                         for ext in ('json','log','memory.json','gpu.json','gpu.csv')]
                paths.append(destination.with_suffix('.sampling-memory.json'))
                paths += [artifacts/name for name in ('latents.pt','refine-input.pt','rgb.npy','audio.npy','audio.wav','video.json')]
                for path in paths:
                    if path.exists():
                        path.rename(retained / path.name)
                save(retained / 'attempt.json', row)
                # Reuse only completed sampling from this request, never a
                # partial sample. The worker validates provenance and tensor
                # metadata again before loading the saved video/audio latents.
                # The controller's durable row can still say ``sample`` when
                # the worker has already written a complete sampling receipt
                # and is failing while releasing streamed weights.  The
                # worker receipt is authoritative: inspect it regardless of
                # the parent monitor phase, then require completed_sampling()
                # to validate all planned finite steps, provenance, and the
                # retained latent checkpoint before switching to decode-only.
                if resume_decode is None:
                    try:
                        sample_metrics = retained / destination.with_suffix('.engine.json').name
                        sampled = json.loads(sample_metrics.read_text(encoding='utf-8'))
                        from .decode_resume import completed_sampling
                        if (completed_sampling(sampled)
                                and (retained / 'latents.pt').is_file() and (retained / 'latents.pt').stat().st_size > 0):
                            resume_decode = dict(latents=str(retained / 'latents.pt'),
                                metrics=str(sample_metrics), request=str(retained / 'video.json'))
                    except (OSError, ValueError, TypeError):
                        pass  # Older/incomplete artifacts retain full-request recovery.
                # A second-pass failure keeps its completed first pass. Later
                # retries reuse the first retained one; the worker validates
                # its provenance and tensors again before loading it.
                if resume_decode is None and resume_refine is None:
                    try:
                        sample_metrics = retained / destination.with_suffix('.engine.json').name
                        sampled = json.loads(sample_metrics.read_text(encoding='utf-8'))
                        from .decode_resume import refine_checkpoint_complete
                        source = retained / 'refine-input.pt'
                        if (refine_checkpoint_complete(sampled) and source.is_file() and source.stat().st_size > 0
                                and (retained / 'video.json').is_file()):
                            resume_refine = dict(input=str(source), metrics=str(sample_metrics),
                                                 request=str(retained / 'video.json'))
                    except (OSError, ValueError, TypeError):
                        pass
                return str(retained)
            def retry(index, row, selected, decision):
                retry_state = dict(attempt=index + 2, max_attempts=getattr(args, 'resource_retries', 2) + 1,
                                   failed_phase=row.get('phase'), kind=row['failure']['kind'],
                                   reuse_sampling=resume_decode is not None,
                                   reuse_first_pass=resume_decode is None and (resume_refine is not None
                                                                               or preview_pass is not None))
                row['recovery'] = dict(decision, next_profile=selected, **retry_state)
                persist()
                print(json.dumps(dict(event='resource_retry', retained=row['retained'], retry=retry_state)), flush=True)
                from .support_report import write_retry
                write_retry(destination, report, index=index + 1, retained=row['retained'],
                            next_profile=selected, decision=row['recovery'])
            report['video'], report['resources'], profile = execute_attempts(
                history, resource_identity, profile, canvas, launch,
                validate=validate, prepare=forecast,
                archive=archive, report=report, persist=persist, on_retry=retry,
                automatic=not args.profile or getattr(args, 'recover_placement', False),
                max_retries=getattr(args, 'resource_retries', 2))
            report['gpu_card'] = {**report['gpu_card'], **(report['video'].get('gpu_card') or {})}
            if continuation is not None:
                report['continuation']['audio_lead_in_samples'] = report['video'].get('continuation', {}).get(
                    'audio_lead_in_samples', 0)
            if preview:
                # An upscale validates this receipt beside the retained first pass.
                shutil.copyfile(destination.with_suffix('.engine.json'), artifacts / 'first-pass.engine.json')
                from .preview import upscale_reads
                report['preview']['upscale_reads'] = upscale_reads(request['cache'], report['video'], upscaler_checkpoint)
            from .guide_audio import apply_to_report as keep_source_audio, requested as keeps_source_audio
            if keeps_source_audio(media):
                # A preview gets the guide clip's sound too; its upscale reads the retained first pass, not this MP4.
                keep_source_audio(destination, media, report)
            report['success'] = True
    except BaseException as error:
        from .diagnostic_resources import exception_details
        report['exception'] = exception_details(error)
        error.diagnostic_recorded = True
        report['error'] = repr(error)
        report['error_message'] = str(error)
        report['error_type'] = type(error).__name__
        if hasattr(error, 'details'):
            report['resource_error'] = error.details
        _runtime_libraries(error, report)
        if applied:
            report['tuning']['disabled_after_failure'] = tuning.disable_profile(applied, error)
        raise
    finally:
        processes.restore_handlers(previous)
        report['request_seconds'] = time.perf_counter() - started
        diagnostic = write_debug(destination, report)
        if diagnostic:
            report['diagnostic_file'] = diagnostic.name
        save(destination.with_suffix('.request.json'), report)


if __name__ == '__main__':
    main()