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.

162 KB
Raw Blame
"""Linux/Windows bootstrap. Python preflight uses stdlib and curl, without installation writes."""
from __future__ import annotations
import argparse
import csv
from contextlib import ExitStack, contextmanager
import hashlib
import json
import shlex
import logging
import os
from pathlib import Path
import platform
import re
import shutil
import signal
import subprocess
import sys
import tarfile
import tempfile
import time
import threading
import urllib.request
import zipfile
from urllib.parse import unquote, urlsplit

from . import execution_paths
from .hardware import Hardware, GiB, cgroup_capacity
from . import __version__, subprocess_output
from .policy import resource_budget
from .monitoring import save
from .install_tuning import build_parallelism, required_models, cache_compatible, wheel_key
from .terminal_ui import TerminalUI, LogProgress
from .locking import runtime_lock, LOCK_ENV
from .environments import (ENVIRONMENTS, environment_names, select_layout, role_pythons, constraints_file,
                           bootstrap_versions, uv_file_arguments, uv_build_environment)
from . import disk_space
from . import network
from .comfy_environment import with_private_compiler
from . import processes
from .system import install_root, venv_python, system_memory, nvidia_smi, memory_sample, curl_executable, missing_curl_message
from .system import inference_headroom

PACKAGE = Path(__file__).resolve().parent
SOURCE = PACKAGE.parent
DEFAULT_ROOT = install_root()


def _permission_limited_memory_sample(row):
    """Whether only descendant process queries were denied by Windows.

    Windows can deny PROCESS_QUERY_LIMITED_INFORMATION for a child owned by a
    different security context even though the install process and the system
    memory counters remain readable.  In that case the process-tree number is
    incomplete, but the global emergency floor is still a valid safety guard.
    Require a real sampled process count to distinguish denied child queries
    from a failed process snapshot.
    """
    if type(row.get('processes')) is not int or row['processes'] <= 0:
        return False
    pids = row.get('unreadable_memory_pids', row.get('unreadable_pss_pids', []))
    errors = row.get('memory_read_errors', [])
    if not pids or not errors:
        return False
    if not all(type(pid) is int and pid > 0 for pid in pids):
        return False
    return all(type(error) is dict and error.get('winerror') == 5 for error in errors)


def setup_memory_status(row, verbose=False, *, system=None):
    available = (inference_headroom(row) if (system or platform.system()) == 'Linux'
                 else row.get('effective_available_bytes', row['system_available_bytes']))
    if memory_sample(row) is None:
        if row.get('monitor_status') == 'degraded':
            return 'Process RAM partially unavailable · %.1f GiB available · continuing with system floor' % (available/GiB)
        return 'Process RAM reading unavailable · %.1f GiB available · retrying' % (available/GiB)
    if row.get('private_commit_bytes') is not None:
        # Commit includes nonresident reservations; displaying it as RAM hid
        # the cause of Windows file-mapping failures while physical RAM was free.
        return ('RAM %.1f GiB · Commit %.1f GiB · Free RAM %.1f GiB · Free Commit %.1f GiB' %
                (row['rss_bytes']/GiB, row['private_commit_bytes']/GiB,
                 row['system_physical_available_bytes']/GiB, row['system_commit_available_bytes']/GiB))
    result = ('RAM %s %.2f GiB · system available %.2f GiB' %
              (row.get('guard_metric', 'PSS'), (memory_sample(row) or 0)/GiB, available/GiB)
              if verbose else 'Setup processes %.1f GiB · %.1f GiB available' %
              ((memory_sample(row) or 0)/GiB, available/GiB))
    if (row.get('cgroup_memory') or {}).get('limit_bytes') is not None:
        result += ' within container limit'
    return result


# Windows setup downloads and unpacks prebuilt wheels: a real install peaked
# near 0.93 GiB of tree private working set. The planned budget is the memory
# free when planning minus the 2 GiB reserve, so on a machine with 2 GiB or
# less free it was 0 and the first sample stopped the install.
WINDOWS_SETUP_MIN_PROCESS_BUDGET = 2 * GiB


def setup_memory_pressure(row, budget, system):
    """Keep Windows planning headroom separate from an exhaustion stop.

    The budget already excludes the OS reserve. Model SDKs additionally
    switch to bounded streaming below 2 GiB; stopping the whole installer at
    that same threshold prevented the low-memory path from continuing.
    Linux uses inference's clean-file-cache headroom, retaining the 1 GiB
    floor and the separate process budget. Raw cgroup charges remain recorded.
    On Windows the process budget never falls below what setup itself needs;
    a machine with little free RAM is stopped by the commit and system floors
    when it truly runs out, not by a budget that was planned as zero.
    """
    planned_budget = budget
    raised = system == 'Windows' and budget < WINDOWS_SETUP_MIN_PROCESS_BUDGET
    if raised:
        budget = WINDOWS_SETUP_MIN_PROCESS_BUDGET
    reserve = (2 if system == 'Windows' else 1) * GiB
    # A raised budget keeps the full 256 MiB stop point: 5% of the raised
    # budget would stop a machine with little free RAM later than any other.
    floor = (256 * 2**20 if raised else min(256 * 2**20, int(budget * .05))) if system == 'Windows' else reserve
    available = (inference_headroom(row) if system == 'Linux'
                 else row.get('effective_available_bytes', row['system_available_bytes']))
    commit = row.get('system_commit_available_bytes')
    used = memory_sample(row)
    reasons = []
    if commit is not None and commit <= floor:
        reasons.append('commit_headroom')
    elif available <= floor:
        reasons.append('system_headroom')
    if used is not None and used > budget:
        reasons.append('process_budget')
    return dict(reasons=reasons, working_bytes=used, budget_bytes=budget, planned_budget_bytes=planned_budget,
                guard_metric=row.get('guard_metric', 'process working memory'),
                available_bytes=available, physical_available_bytes=row.get('system_physical_available_bytes'),
                commit_available_bytes=commit, emergency_floor_bytes=floor,
                planning_reserve_bytes=reserve)


def setup_memory_failure(pressure):
    reason = pressure['reasons'][0]
    if reason == 'commit_headroom':
        detail = 'Installation paused: Windows commit headroom is nearly exhausted (%.2f GiB available; %.2f GiB minimum).' % (
            pressure['commit_available_bytes'] / GiB, pressure['emergency_floor_bytes'] / GiB)
    elif reason == 'system_headroom':
        detail = 'Installation paused: system RAM is nearly exhausted (%.2f GiB available; %.2f GiB minimum).' % (
            pressure['available_bytes'] / GiB, pressure['emergency_floor_bytes'] / GiB)
    else:
        # The budget is the memory free at planning minus the reserve, and setup itself
        # peaked near 1 GiB; so the free memory needed is the reserve plus that, rounded up to
        # the next half GiB above it, which leaves some room.
        needed = (pressure.get('planning_reserve_bytes') or 0) + max(pressure['working_bytes'], GiB)
        detail = ('Installation crossed its RAM budget (%.2f GiB used; %.2f GiB budget; %s). '
                  'At least %.1f GiB of RAM must be free when it starts.') % (
            pressure['working_bytes'] / GiB, pressure['budget_bytes'] / GiB, pressure['guard_metric'],
            (needed * 2 // GiB + 1) / 2)
    return detail + ' Downloaded files are retained.'


def reinstall_download_bytes(dependencies, system, *, root=None, frontend_python=None, disk_mode='normal'):
    """Bytes setup downloads again to replace missing or changed files: the pinned
    Windows wheel (torch_download), elsewhere the package's installed size, an
    upper bound for its wheel. Marks each engine environment's damaged packages."""
    from .environments import ENVIRONMENTS
    from .runtime_libraries import damaged, incomplete, installed_bytes, missing_packages
    from .torch_download import select
    total = 0
    seen = set()
    environments = [] if system == 'Darwin' else [(name, row, False) for name, row in dependencies.items()]
    if frontend_python:
        # comfy_host matches the engine Python's packages after engine repair.
        name = 'unified' if 'unified' in dependencies else 'engine'
        environments.append((name, dict(python=str(frontend_python), exists=Path(frontend_python).is_file()), True))
    for name, row, frontend in environments:
        if not row.get('exists'):
            continue
        row['damaged'] = broken = damaged(row['python'])
        if frontend:
            broken = sorted(set(broken + incomplete(row['python'])))
        else:
            # Setup puts back pinned packages whose files are gone (Setup.repairing).
            broken = sorted(set(broken + missing_packages(row['python'], constraints_file(name, system))))
        pins = ENVIRONMENTS.get(name, {})
        wheels = {w['package']: w for w in (select(pins['torch'], pins['cuda']) or [])} if system == 'Windows' and pins else {}
        for package in broken:
            wheel = wheels.get(package)
            if wheel is None:
                total += installed_bytes(row['python'], package)
                continue
            if frontend and disk_mode == 'extreme':
                # Engine setup clears these wheels before the launcher repairs ComfyUI.
                total += wheel['bytes']
                continue
            key = (wheel['package'], wheel['version'])
            if key in seen:
                continue
            seen.add(key)
            if root is not None:
                cached = Path(root) / 'downloads' / 'torch-wheels' / wheel['filename']
                try:
                    if cached.is_file() and cached.stat().st_size == wheel['bytes'] and digest(cached) == wheel['sha256']:
                        continue
                except OSError:
                    pass
            total += wheel['bytes']
    return total


def download_bytes(plan):
    """What a reviewed plan downloads: models plus packages reinstalled over changed files."""
    return (plan.get('model_download_bytes') or 0) + (plan.get('package_download_bytes') or 0)


def dependency_status(root, layout='unified', system=None):
    """Inspect distribution metadata only: no tensor imports or downloads."""
    result = {}
    system = system or platform.system()
    if system == 'Darwin':
        from .macos_bootstrap import dependency_status as native_status
        return native_status(root)
    packages = {
        'engine': ['torch', 'torchvision', 'triton', 'transformers', 'accelerate', 'peft', 'safetensors',
                   'huggingface-hub', 'omegaconf', 'pyyaml', 'einops', 'numpy', 'pillow', 'av',
                   'psutil', 'tqdm', 'importlib-metadata', 'requests', 'httpx', 'socksio', 'pysocks',
                   'modelscope-hub', 'hf-xet', 'sageattention', 'diffusers', 'freevideo-engine'],
        'encoder': ['torch', 'torchvision', 'torchaudio', 'freevideo-engine'] +
                   [s.strip() for s in (SOURCE / 'constraints/encoder-runtime.txt').read_text(encoding='utf-8').splitlines()
                    if s.strip() and not s.startswith('#')]}
    packages['unified'] = sorted(set(packages['engine'] + packages['encoder']))
    if system == 'Windows':
        for name in packages:
            packages[name] = ['triton-windows' if p == 'triton' else p for p in packages[name]]
    for name in environment_names(layout):
        names = packages[name]
        expected = dict(line.strip().lower().split('==', 1) for line in
                        constraints_file(name, system).read_text(encoding='utf-8').splitlines() if '==' in line)
        expected = {name.replace('_', '-'): version for name, version in expected.items()}
        expected.update({'freevideo-engine': __version__, 'sageattention': '2.2.0'})
        if system == 'Windows':
            expected['sageattention'] = json.loads((PACKAGE / 'bootstrap_versions.json').read_text(encoding='utf-8'))['windows']['sageattention']['version']
        python = venv_python(root / 'envs' / name, system)
        row = {'python': str(python), 'exists': python.exists(), 'installed': {}, 'missing': sorted(set(names)), 'mismatched': {}}
        if python.exists():
            code = ('import importlib.metadata as m,json; '
                    'print(json.dumps({d.metadata["Name"].lower().replace("_","-"):d.version for d in m.distributions()}))')
            check = subprocess_output.run_python([str(python), '-B', '-c', code], capture_output=True)
            if check.returncode:
                row['error'] = check.stderr[-1000:]
            else:
                installed = json.loads(check.stdout)
                row['installed'] = {p: installed.get(p) for p in sorted(set(names))}
                row['missing'] = [p for p in sorted(set(names)) if p not in installed]
                row['mismatched'] = {p: {'installed': installed[p], 'required': expected[p]}
                    for p in names if p in installed and p in expected and installed[p] != expected[p]}
        result[name] = row
    return result


def torch_stack(name):
    """A package whose change brings a new PyTorch build and, on Linux, its CUDA wheels."""
    return name in ('torch', 'torchvision', 'torchaudio') or name.startswith(('nvidia-', 'cuda-'))


def environment_seeded(folder):
    """An environment uv seeded with pip: the folder has one, as `uv venv --seed` leaves it."""
    folder = Path(folder)
    return any(folder.glob('Lib/site-packages/pip')) or any(folder.glob('lib/python*/site-packages/pip'))


def environment_in_place(row, python_version):
    """An existing environment that only lacks ordinary packages: setup adds them beside the rest."""
    if not row.get('exists') or row.get('error'):
        return False
    if any(torch_stack(name) for name in [*row.get('missing', []), *row.get('mismatched', {})]):
        return False
    try:
        config = (Path(row['python']).parent.parent / 'pyvenv.cfg').read_text(encoding='utf-8')
    except OSError:
        return False
    found = re.search(r'^version(?:_info)?\s*=\s*([\d.]+)\s*$', config, re.M)
    return bool(found) and found.group(1) == python_version


def environment_allowance_gib(dependencies, *, mac, layout, python_version):
    """Disk for the Python environments, by what setup will actually install."""
    ready = all(r['exists'] and not r['missing'] and not r['mismatched'] for r in dependencies.values())
    if mac:
        # A Mac environment has no CUDA packages: a fresh one measured 4.3 GB
        # including the package cache, against 30 GiB allowed for CUDA ones.
        return 1 if ready else 6
    if ready:
        return 5
    if all(environment_in_place(r, python_version) for r in dependencies.values()):
        # A repair that adds ordinary packages. Even reinstalling the whole
        # Windows PyTorch as a copy (cuDNN repair) is a 1.78 GiB wheel plus
        # about 4.5 GB installed; a Linux unified environment is 5.3 GiB in all.
        return 10
    # New environments, or a new PyTorch stack or Python: downloaded afresh.
    return 30 if layout == 'unified' else 45


def digest(path, algorithm='sha256', git_blob=False):
    h = hashlib.new(algorithm)
    if git_blob:
        h.update(('blob %d\0' % path.stat().st_size).encode())
    with path.open('rb') as stream:
        for chunk in iter(lambda: stream.read(8 * 1024 * 1024), b''):
            h.update(chunk)
    return h.hexdigest()


def inventory(gpu=None):
    query = 'index,uuid,name,compute_cap,memory.total,memory.free,driver_version,pci.bus_id'
    selector = gpu if gpu is not None else os.environ.get('CUDA_VISIBLE_DEVICES', '0').split(',')[0]
    detection = {}
    try:
        smi = nvidia_smi()
        result = subprocess_output.run_external([smi, '--query-gpu=' + query, '--format=csv,noheader,nounits'],
                                check=True, capture_output=True, timeout=20)
        rows = [dict(zip(query.split(','), map(str.strip, row))) for row in csv.reader(result.stdout.splitlines())]
        if not rows or any(set(row) != set(query.split(',')) for row in rows):
            raise ValueError('nvidia-smi returned an incomplete GPU inventory')
        # Unsupported numeric fields are also a failed observation, not proof
        # that the user has no GPU. Only the selected row has to be readable;
        # another GPU reporting N/A must not block an installation that worked.
        matches = [r for r in rows if r['index'] == selector or r['uuid'] == selector]
        if len(matches) == 1:
            row = matches[0]
            float(row['memory.total']), float(row['memory.free'])
            int(row['driver_version'].split('.')[0])
            capability = tuple(map(int, row['compute_cap'].split('.')))
            if len(capability) != 2 or capability[0] <= 0 or not 0 <= capability[1] <= 9:
                raise ValueError('nvidia-smi returned an unknown compute capability: ' + row['compute_cap'])
    except (OSError, RuntimeError, ValueError, subprocess.SubprocessError) as error:
        from . import cuda_inventory
        try:
            fallback = cuda_inventory.probe(selector)
        except (OSError, RuntimeError, ValueError, subprocess.SubprocessError) as fallback_error:
            raise RuntimeError('GPU detection failed. nvidia-smi: %s; CUDA: %s. '
                               'Check device access and the NVIDIA driver, then retry setup.' %
                               (error, fallback_error)) from fallback_error
        selected, rows = fallback['selected_gpu'], fallback['gpus']
        detection = dict(cuda_driver_api_version=fallback['cuda_driver_api_version'],
            warnings=[cuda_inventory.WARNING],
            gpu_detection=dict(source='cuda-driver', nvidia_smi_error=str(error),
                nvidia_smi_returncode=getattr(error, 'returncode', None),
                nvidia_smi_stderr=getattr(error, 'stderr', None)))
        logging.getLogger(__name__).info('%s nvidia-smi: %s', cuda_inventory.WARNING, error)
    else:
        if len(matches) != 1:
            raise ValueError('Select one physical GPU by nvidia-smi index or full UUID with --gpu. MIG is not supported.')
        selected = matches[0]
    try:
        capability = tuple(map(int, selected['compute_cap'].split('.')))
        if len(capability) != 2:
            capability = (0, 0)
    except (TypeError, ValueError):
        # Keep the raw driver result in inventory for the exported report.
        # Unknown must not be presented as an unsupported old GPU architecture.
        capability = (0, 0)
    ram = system_memory()
    limit, available = cgroup_capacity(include_reclaimable=True)
    hardware = Hardware(selected['name'], capability,
        int(float(selected['memory.total']) * 2**20), int(float(selected['memory.free']) * 2**20),
        ram['total_bytes'], min(ram['available_bytes'], available) if available is not None else ram['available_bytes'],
        platform.system(), cgroup_ram_limit=limit, gpu_uuid=selected['uuid'],
        driver_version=selected['driver_version'])
    return {'hardware': hardware.to_dict(), 'selected_gpu': selected, 'gpus': rows,
            'kernel': platform.release(), 'platform': platform.platform(), 'machine': platform.machine(),
            'cpu_threads': os.cpu_count(), 'swap_total_bytes': ram.get('swap_total_bytes'),
            'swap_free_bytes': ram.get('swap_free_bytes'), 'system_memory': ram,
            'compiler': shutil.which('cl' if platform.system() == 'Windows' else 'g++'), 'git': usable_git(),
            'git_found': shutil.which('git'), **detection}


# Windows reuses a detected Git from 2.35, the oldest tested there, and
# otherwise installs its own MinGit.
WINDOWS_MIN_GIT = (2, 35)
# Seconds to wait before creating an environment again after another program held a file.
ENVIRONMENT_BUSY_WAITS = (3, 10, 30)


def git_floor(system=None):
    return WINDOWS_MIN_GIT if (system or platform.system()) == 'Windows' else network.MIN_GIT


def usable_git(path=None, env=None):
    """The Git on PATH when it is new enough for clone(); None otherwise."""
    executable = shutil.which('git', path=path)
    version = network.git_version(executable, env) if executable else None
    return executable if version and version >= git_floor() else None


def gcc_major(executable, env=None):
    """Major version of a GCC driver, or None when it does not run or does not answer like GCC."""
    try:
        text = subprocess_output.output_external([str(executable), '-dumpfullversion', '-dumpversion'], env=env,
                                                 stderr=subprocess.DEVNULL, timeout=30)
        return int(text.split()[0].split('.')[0])
    except (OSError, subprocess.SubprocessError, ValueError, IndexError):
        return None


def host_compiler_choice(below, path=None, env=None, find=shutil.which, major=gcc_major):
    """Which C/C++ compiler builds GPU code when the toolkit accepts GCC only below major version `below`.

    ({}, ...) when the system compiler is accepted, or when its version cannot be told: the build then
    behaves as it always did. ({'CC': ..., 'CXX': ...}) when it is too new and a versioned pair
    (g++-15 and gcc-15 ...) is installed beside it. None when no installed compiler is accepted.
    """
    system = find('g++', path=path)
    version = major(system, env) if system else None
    if version is None or version < below:
        return {}
    for candidate in range(below - 1, 8, -1):
        cxx, cc = find('g++-%d' % candidate, path=path), find('gcc-%d' % candidate, path=path)
        if cxx and cc and major(cxx, env) == candidate and major(cc, env) == candidate:
            return {'CC': cc, 'CXX': cxx}
    return None


def pinned_compiler_identity(spec=None):
    """How FreeVideo's own GCC is named in the wheel cache key and in a build record."""
    spec = spec or json.loads((PACKAGE / 'gcc_linux.json').read_text(encoding='utf-8'))
    return 'conda-forge gcc ' + spec['version'] + ' static-libstdc++'


def existing_parent(path):
    while not path.exists():
        path = path.parent
    return path


def prepared_precision(prepared):
    """Display name of a prepared model's weight format (Macs use the ConvRot int8 export)."""
    return 'ConvRot int8' if (prepared or {}).get('scale_granularity') == 'int8_convrot' else 'FP8'


def model_target(row, model_dir, encoder_dir, prepared_dir=None):
    from .model_status import family
    if family(row) == 'image':
        from .image_gen.image_pack import target
        return target(row, model_dir)
    if row.get('sampling_file'):
        from .adaln_assets import asset_path
        from .sampling_assets import cache_root
        return asset_path(cache_root(model_dir), row['sampling_file'])
    if row.get('role') == 'latent_upscaler':
        return model_dir / 'latent_upscaler' / Path(row['file']).name
    if row.get('prepared'):
        if prepared_dir is None:
            raise ValueError('Prepared model download has no destination directory')
        from .adaln_assets import asset_path
        return asset_path(prepared_dir, row['file'])
    return (model_dir if row['repo'].startswith('OpenVDN/') else encoder_dir) / row['file']


def installation_model_files(prepared, reuse_cache, sampling_caches):
    """The file selection shared by planning and provisioning."""
    from . import prepared_model
    from .sampling_assets import install_files, usable_with
    files = list(required_models(json.loads((PACKAGE / 'model_files.json').read_text(encoding='utf-8')),
                                 reuse_cache or prepared))
    files += prepared_model.files(prepared)
    if prepared or (reuse_cache and usable_with(reuse_cache)):
        files += install_files(bool(sampling_caches))
    return files


def resolve_prepared_format(requested, saved, hardware):
    """The prepared model format of this setup run: 'int8_convrot' or 'fp8'.

    An explicit choice wins. Otherwise an installation keeps the format it
    recorded, and one from before the choice existed keeps its FP8 model, so an
    update never starts a model download by itself. A fresh installation takes
    the faster format for its GPU.
    """
    choices = {'int8': 'int8_convrot', 'int8_convrot': 'int8_convrot', 'fp8': 'fp8'}
    if requested in choices:
        return choices[requested]
    if requested not in (None, 'auto'):
        raise ValueError('Unknown prepared model format: ' + str(requested))
    recorded = saved.get('prepared_format')
    if recorded in ('int8_convrot', 'fp8'):
        return recorded
    if saved.get('cache'):
        return 'fp8'
    from .prepared_model import preferred_format
    return preferred_format(hardware) or 'fp8'


def require_int8_kernels(plan, kernel_report):
    """Stop a setup that installs the int8 model unless its GPU kernels passed on this machine.

    machine.json is written only after every step, so the installation keeps
    the model it had.
    """
    if plan.get('prepared_format') != 'int8_convrot' or plan.get('inventory', {}).get('hardware', {}).get('system') == 'Darwin':
        return
    from .kernel_capabilities import readiness
    rows = json.loads(Path(kernel_report).read_text(encoding='utf-8')).get('kernel_probes', [])
    if not readiness(rows).get('int8_ready'):
        raise RuntimeError('The int8 model needs int8 GPU kernels, and they did not pass on this GPU. The '
                           'installation keeps its current model. Details: ' + str(kernel_report))


def offline_installation(root):
    """Whether an engine folder belongs to an installation from offline packages."""
    return (root.parent / 'portable.json').is_file()


PREPARE_KEY = 'install-prepare'


def prepare_step(ui, name, done=None, total=None):
    """One running task for the silent steps between the model scan and the first real task.

    Without it the card keeps the last finished event (the model scan) for as long as the
    environment, the network and the download tools are examined.
    """
    with ui._lock:
        if PREPARE_KEY not in ui.tasks:
            ui.begin(PREPARE_KEY, 'Preparing installation')
        elif ui.tasks[PREPARE_KEY]['state'] != 'running':
            return  # Finished: a late step must not bring the card back to it.
        if ui.tasks[PREPARE_KEY].get('step') != name:
            ui.tasks[PREPARE_KEY]['event_tick'] = 0.  # Short steps must each reach the card.
        ui.tasks[PREPARE_KEY]['step'] = name
        shown = '%s %d / %d' % (name, done or 0, total) if total else name
        ui.update(PREPARE_KEY, activity='note', name=shown, detail=shown, unit='items',
                  done=done or 0, total=total or 0)


def prepare_end(ui, success=True):
    """Finish the step once; a repeated end would bring its finished line back as the card's last event."""
    with ui._lock:
        if ui.tasks.get(PREPARE_KEY, {}).get('state') == 'running':
            ui.end(PREPARE_KEY, success=success)


def plan(args, *, local_progress=None, stage=None):
    root = args.root.expanduser().resolve()
    warnings = []
    saved = json.loads((root / 'machine.json').read_text(encoding='utf-8')) if (root / 'machine.json').is_file() else {}
    storage = getattr(args, 'storage', None) or saved.get('storage', 'compact')
    layout = select_layout(getattr(args, 'environment', None), saved)
    # v0.2.0 stored the encoder directory only in its retained setup plan.
    prior_path = Path(saved['setup_run']) / 'plan.json' if saved.get('setup_run') else None
    prior = json.loads(prior_path.read_text(encoding='utf-8')) if prior_path and prior_path.is_file() else {}
    # Hardware detection is the default for fresh installs, updates and retries.
    # Saved benchmark caps must never silently follow a user onto a larger GPU.
    keep_limits = getattr(args, 'keep_resource_limits', False)
    vram_gib = args.vram_gib if args.vram_gib is not None else saved.get('vram_gib') if keep_limits else None
    ram_gib = args.ram_gib if args.ram_gib is not None else saved.get('ram_gib') if keep_limits else None
    fixture = json.loads(args.hardware_json.read_text(encoding='utf-8')) if args.hardware_json else None
    mac_target = (fixture or {}).get('hardware', {}).get('system', platform.system()) == 'Darwin'
    if mac_target:
        from .macos_bootstrap import preflight
        snapshot, resources, errors = preflight(args, fixture, ram_gib=ram_gib, vram_gib=vram_gib)
        system, windows_target, layout = 'Darwin', False, 'unified'
        cache_format = dict(capability=None, scale_granularity='int8_convrot')
        prepared_format = 'int8_convrot'
    else:
        if not args.hardware_json and (platform.system() not in ('Linux', 'Windows') or platform.machine().lower() not in ('x86_64', 'amd64')):
            raise RuntimeError('One-click setup supports Linux x86_64 and native Windows x64.')
        snapshot = json.loads(args.hardware_json.read_text(encoding='utf-8')) if args.hardware_json else inventory(args.gpu)
        warnings.extend(snapshot.get('warnings', []))
        hardware = Hardware.from_dict(snapshot['hardware'])
        errors = []
        if snapshot.get('machine', '').lower() not in ('x86_64', 'amd64') or hardware.system not in ('Linux', 'Windows'):
            errors.append('This installer supports Linux x86_64 and native Windows x64.')
        windows_target = hardware.system == 'Windows'
        if windows_target and layout != 'unified':
            errors.append('Native Windows uses the unified environment. Rerun with --environment unified.')
            layout = 'unified'
        if windows_target and getattr(args, 'rebuild_sage', False):
            errors.append('Windows uses the tested Sage2 wheel; --rebuild-sage is a Linux source-build option.')
        driver = str(snapshot['selected_gpu']['driver_version']).strip()
        # An unreadable version is left to the later checks instead of blocking setup.
        major = re.match(r'\d+', driver)
        cuda_api = snapshot.get('cuda_driver_api_version')
        if cuda_api < 13000 if cuda_api is not None else (major and int(major.group()) < 580):
            # The card names the graphics card too; brackets would end its pattern early.
            model = re.sub(r'[()\r\n]', '', str(snapshot['selected_gpu'].get('name') or '')).strip()
            # The CUDA fallback reads no driver version; leave it out instead of printing a gap.
            errors.append('NVIDIA driver%s%s is older than 580, the minimum for the CUDA 13 encoder; update the driver first.'
                          % (' ' + driver if driver else '', ' (%s)' % model if model else ''))
        compatibility = hardware.cuda_compatibility()
        if compatibility['error']:
            errors.append(compatibility['error'])
        snapshot['cuda_compatibility'] = compatibility
        # A missing or too old Git is replaced by FreeVideo's own.
        if offline_installation(root):
            # Its sources carry no Git history and its Python is the package's.
            errors.append('This folder holds an installation from offline packages; automatic installation does not change it. '
                          'Open it from the launcher, or choose another folder for an automatic installation.')
        curl_env = dict(os.environ, FREEVIDEO_HOME=str(root))
        if not args.hardware_json and curl_executable(curl_env) is None:
            errors.append(missing_curl_message(curl_env))
        resources = None
        try:
            resources = resource_budget(hardware, vram_gib=vram_gib, ram_gib=ram_gib)
            resources['ram_budget_bytes'] = max(0, resources['ram_budget_bytes'])
        except ValueError as error:
            errors.append(str(error))
        system = hardware.system
        cache_format = dict(capability=hardware.capability)
        prepared_format = resolve_prepared_format(getattr(args, 'prepared_format', 'auto'), saved, hardware)
        if (prepared_format == 'int8_convrot' and getattr(args, 'prepared_format', 'auto') in (None, 'auto')
                and getattr(args, 'reuse_models', None) and not getattr(args, 'cache', None)):
            # A fresh installation pointed at an existing FP8 model reuses it
            # instead of downloading the int8 one; switching stays a choice.
            from . import install_tuning
            if (install_tuning.discover_prepared(args.reuse_models, hardware.capability, scale_granularity='int8_convrot') is None
                    and install_tuning.discover_prepared(args.reuse_models, hardware.capability) is not None):
                prepared_format = 'fp8'
        if getattr(args, 'cache', None) and getattr(args, 'prepared_format', 'auto') in (None, 'auto'):
            # An explicitly named cache keeps its own format.
            prepared_format = ('int8_convrot' if cache_compatible(args.cache, hardware.capability, scale_granularity='int8_convrot')
                               else 'fp8')
        if prepared_format == 'int8_convrot':
            cache_format['scale_granularity'] = 'int8_convrot'
    model_dir = Path(args.models or saved.get('model_root') or root / 'models' / 'vdn').expanduser().resolve()
    encoder_dir = Path(args.encoder_models or saved.get('encoder_model_root') or prior.get('encoder_dir') or root / 'models' / 'encoder').expanduser().resolve()
    reuse_cache = args.cache.expanduser().resolve() if args.cache else None
    if reuse_cache is None and not getattr(args, 'rebuild_cache', False):
        revision = json.loads((PACKAGE / 'dependencies.json').read_text(encoding='utf-8'))['models']['vdn_revision']
        for name in ('machine.json', 'prepared-cache.json'):
            cache_record = root / name
            if cache_record.is_file():
                record = json.loads(cache_record.read_text(encoding='utf-8'))
                candidate = record.get('cache')
                if record.get('model_revision') == revision and candidate and cache_compatible(candidate, **cache_format):
                    reuse_cache = Path(candidate)
                    break
    if reuse_cache is None and not getattr(args, 'rebuild_cache', False):
        from .install_tuning import discover_prepared
        reuse_cache = discover_prepared(getattr(args, 'reuse_models', None), **cache_format)
    from . import prepared_model
    prepared = None
    model_source = getattr(args, 'model_source', 'prepared')
    if reuse_cache is None and not getattr(args, 'rebuild_cache', False) and model_source == 'prepared':
        prepared = prepared_model.select(root=root, **cache_format)
    prepared_dir = prepared['directory'] if prepared else None
    if mac_target and reuse_cache is None and prepared is None:
        errors.append('No verified native-compatible prepared model is available. Source conversion is not supported on Mac.')
    # New installations prepare every quality level; an existing one keeps its
    # earlier choice (off if it predates the option) unless the flag says otherwise.
    sampling_caches = getattr(args, 'sampling_caches', None)
    if sampling_caches is None:
        sampling_caches = prior['sampling_caches'] if isinstance(prior.get('sampling_caches'), bool) else not saved.get('ready')
    sampling_caches = bool(sampling_caches)
    files = installation_model_files(prepared, reuse_cache, sampling_caches)
    local_reuse = None
    local_folder = getattr(args, 'reuse_models', None)
    local_manifest = getattr(args, 'reuse_models_manifest', None)
    from .launcher_settings import saved_model_libraries
    saved_libraries = saved_model_libraries()
    if local_folder or local_manifest or saved_libraries:
        from .local_models import scan, scan_many, can_link, key as local_key
        previous_reuse = None
        approved = getattr(args, 'approved_plan', None)
        if approved:
            previous_reuse = json.loads(Path(approved).read_text(encoding='utf-8')).get('local_models')
        scan_cache = root / 'local-model-scan.json'
        if not previous_reuse and scan_cache.is_file():
            # What an earlier check hashed; scan() still hashes any file whose size, times or inode changed.
            try:
                previous_reuse = json.loads(scan_cache.read_text(encoding='utf-8'))
            except (OSError, ValueError):
                previous_reuse = None
            if not (isinstance(previous_reuse, dict) and isinstance(previous_reuse.get('matches'), dict)):
                previous_reuse = None
        needed = [row for row in files if not model_target(row, model_dir, encoder_dir, prepared_dir).exists()]
        if local_manifest:
            if Path(local_manifest).stat().st_size > 512 * 1024:
                raise ValueError('Model library manifest is too large')
            libraries = json.loads(Path(local_manifest).read_text(encoding='utf-8'))
            if not isinstance(libraries, dict) or libraries.get('version') != 1 or not isinstance(libraries.get('roots'), list):
                raise ValueError('Invalid model library manifest')
            directories = ([str(local_folder)] if local_folder else []) + libraries['roots']
            from .local_models import library_roots
            directories = library_roots(library_roots(directories) + saved_libraries, keep_first=True)
            scan_library = lambda: scan_many(directories, needed, prior=previous_reuse, callback=local_progress)
        elif saved_libraries:
            from .local_models import library_roots
            directories = library_roots(([str(local_folder)] if local_folder else []) + saved_libraries, keep_first=True)
            scan_library = lambda: scan_many(directories, needed, prior=previous_reuse, callback=local_progress)
        else:
            scan_library = lambda: scan(local_folder, needed, prior=previous_reuse, callback=local_progress)
        try:
            local_reuse = scan_library()
        except OSError as error:
            if not getattr(args, 'download_list', False):
                raise
            from .model_guidance import DownloadListError
            original = str(error)
            if error.__cause__ is not None:
                original += '\n' + str(error.__cause__)
            raise DownloadListError('read', original_error=original) from error
        if local_reuse['matches'] and root.is_dir():
            try:
                save(scan_cache, dict(root=local_reuse['root'], matches=local_reuse['matches']))
            except OSError:
                pass  # The next check hashes again; nothing depends on this file.
        local_reuse['copy_mode'] = bool(getattr(args, 'copy_existing_models', False))
        local_reuse['copy_bytes'] = local_reuse['linked_bytes'] = 0
        for row in needed:
            record = local_reuse['matches'].get(local_key(row))
            if record:
                parent = existing_parent(model_target(row, model_dir, encoder_dir, prepared_dir).parent)
                record['method'] = 'hardlink' if not local_reuse['copy_mode'] and can_link(record['source'], parent) else 'copy'
                local_reuse['linked_bytes' if record['method'] == 'hardlink' else 'copy_bytes'] += row['bytes']
    groups = {}
    present = 0
    model_entries = []
    from . import model_repair
    mismatches = model_repair.read(root)
    replace_models = []
    reserved = set()
    check_download_list = bool(getattr(args, 'download_list', False))
    stamps_path = root / 'verified-models.json'
    stamps = json.loads(stamps_path.read_text(encoding='utf-8')) if check_download_list and stamps_path.is_file() else {}
    # The check leaves the installer's ledger alone and keeps what it hashed in a file of its own.
    checked_path = root / 'download-list-checks.json'
    try:
        checked = json.loads(checked_path.read_text(encoding='utf-8')) if check_download_list and checked_path.is_file() else {}
    except (OSError, ValueError):
        checked = {}
    ledger_stamps = dict(stamps)
    # A record this check made is newer than the ledger's for the same file whenever the two differ.
    stamps = dict(ledger_stamps, **(checked if isinstance(checked, dict) else {}))
    checked_paths = set()
    for row in files:
        path = model_target(row, model_dir, encoder_dir, prepared_dir)
        replacement = model_repair.replacement(path, row, mismatches, reserved)
        if replacement:
            replace_models.append(replacement)
        size_matches = not replacement and path.is_file() and path.stat().st_size == row['bytes']
        if size_matches and check_download_list:
            # Only the explicit third-party list needs this check during planning.
            # Normal setup keeps its cheap estimate and deferred verification.
            from .provision import verified
            hf_directory = Path(prepared_dir) if row.get('prepared') else model_dir if row['repo'].startswith('OpenVDN/') else encoder_dir
            size_matches = verified(path, row, stamps, mode=getattr(args, 'verify', 'auto'), hf_directory=hf_directory)
            checked_paths.add(str(path))
        present += row['bytes'] if size_matches else 0
        device = existing_parent(path.parent)
        entry = groups.setdefault(str(device), {'path': str(device), 'needed_bytes': 0,
                                                'free_bytes': disk_space.free_bytes(device)})
        local = (local_reuse or {}).get('matches', {}).get(row['repo'] + '/' + row['file'])
        model_entries.append((row, ('verified' if check_download_list else 'found') if size_matches else 'verified' if local else 'download'))
        entry['needed_bytes'] += 0 if size_matches or local and local['method'] == 'hardlink' else row['bytes']
        partial = path.with_suffix(path.suffix + '.partial')
        if not size_matches and not local and partial.is_file() and partial.stat().st_size <= row['bytes']:
            # Only the streaming strategy can reuse this contiguous prefix.
            # Its completed content must still pass the pinned hash check.
            entry['resume_bytes'] = entry.get('resume_bytes', 0) + partial.stat().st_size
    remembered = {name: value for name, value in stamps.items() if name in checked_paths and ledger_stamps.get(name) != value}
    if check_download_list and root.is_dir() and remembered != checked:
        try:
            save(checked_path, remembered)  # The next check does not hash these files again unless they change.
        except OSError:
            pass
    # Stream directly into final FP8 groups. The pinned model occupies ~45.3
    # GiB; allow 52 GiB including the largest group in progress. Never credit
    # future source deletion toward the space needed to complete conversion.
    if stage:
        stage('Checking the environment')
    dependencies = dependency_status(root, layout, system)
    environments_ready = all(r['exists'] and not r['missing'] and not r['mismatched'] for r in dependencies.values())
    python_version = None if mac_target else bootstrap_versions(
        json.loads((PACKAGE / 'bootstrap_versions.json').read_text(encoding='utf-8')), system)['python']
    environment_gib = environment_allowance_gib(dependencies, mac=mac_target, layout=layout, python_version=python_version)
    extra = (0 if reuse_cache or prepared else 52) + environment_gib + 10
    frontend = None
    if getattr(args, 'frontend_root', None):
        frontend = dict(root=str(args.frontend_root.expanduser().resolve()),
                        separate=args.frontend_separate, download=args.frontend_download)
    from .install_disk import budget as disk_budget, frontend_gib as frontend_allowance_gib
    reviewed = (json.loads(Path(args.approved_plan).read_text(encoding='utf-8'))
                if getattr(args, 'approved_plan', None) else saved)
    disk_plan = disk_budget(groups, root, extra,
        eligible=bool(windows_target and layout == 'unified' and (reuse_cache or prepared)
                      and getattr(args, 'model_downloader', 'auto') != 'xet'),
        environments_ready=environments_ready, frontend=frontend,
        keep_extreme=reviewed.get('disk_mode') == 'extreme',
        frontend_gib=frontend_allowance_gib(root, frontend['root'], mac_target) if frontend else disk_space.frontend_gib(mac_target))
    extra = disk_plan['environment_cache_safety_gib']
    errors.extend(disk_plan['errors'])
    # A repair also reinstalls what is damaged in the ComfyUI environment the launcher made.
    frontend_python = getattr(args, 'frontend_repair_python', None)
    if stage:
        stage('Checking the environment')
    package_download_bytes = reinstall_download_bytes(dependencies, system, root=root,
        frontend_python=str(frontend_python.expanduser().absolute()) if frontend_python else None,
        disk_mode=disk_plan['mode'])
    if mac_target:
        errors.extend(disk_space.problem_messages([root, model_dir, encoder_dir] + ([frontend['root']] if frontend else [])))
    if reuse_cache and not cache_compatible(reuse_cache, **cache_format):
        errors.append('--cache must contain a prepared FP8 cache compatible with this GPU scale format.')
    from .download_settings import read as download_preferences
    def native_git_available():
        from .macos_bootstrap import available_git
        return available_git() is not None
    if stage:
        stage('Testing download sources')
    networking = network.plan(json.loads((PACKAGE / 'dependencies.json').read_text(encoding='utf-8')),
        bootstrap_versions(json.loads((PACKAGE / 'bootstrap_versions.json').read_text(encoding='utf-8')), system), layout,
        mode=getattr(args, 'network', 'auto'), timeout=getattr(args, 'network_timeout', 5),
        offline=bool(args.hardware_json or errors),
        git_available=not mac_target or bool(args.hardware_json) or native_git_available(),
        env=dict(os.environ, FREEVIDEO_HOME=str(root)),
        proxy_mode=download_preferences(root / 'download-settings.json')['proxy_mode'],
        progress=(lambda message: stage('Testing download sources', message['done'], message['total'])) if stage else None)
    networking['download_settings_path'] = str(root / 'download-settings.json')
    prepared_missing = prepared and any(
        not model_target(row, model_dir, encoder_dir, prepared_dir).is_file()
        for row in files if row.get('prepared') and not
        (local_reuse or {}).get('matches', {}).get(row['repo'] + '/' + row['file']))
    if prepared_missing and not args.hardware_json and not errors:
        if stage:
            stage('Testing download sources')
        error = prepared_model.access_error(prepared, networking)
        if error:
            errors.append(error)
    from .model_transfer import policy as transfer_policy
    build = build_parallelism(resources['ram_budget_bytes'], snapshot.get('cpu_threads') or 1) if resources and not windows_target and not mac_target else None
    transfers = transfer_policy(resources['ram_budget_bytes'], build['estimated_peak_bytes'] if build else 0) if resources else None
    if disk_plan['mode'] == 'extreme':
        transfers = dict(transfers or {}, file_workers=1, overlap_build=False, mode='streaming-space-saver')
    from .model_status import inventory as model_inventory
    value = {'schema_version': 1, 'engine_version': __version__, 'root': str(root), 'inventory': snapshot, 'policy_estimate': None,
            'installation_resources': resources,
            'storage': storage,
            'disk_mode': disk_plan['mode'], 'disk_policy': disk_plan, 'frontend': frontend,
            'storage_preparation': ('Download verified slim %s weights and fixed AdaLN tables; no original transformer or local conversion'
                                    % prepared_precision(prepared)
                                    if prepared else 'Stream CPU merge directly to FP8 groups; no complete BF16 intermediate cache'),
            'storage_cleanup': ('After cache verification and GPU probes, remove only unchanged conversion-only weights downloaded/copied into this installation; borrowed originals and outputs are retained'
                                if storage == 'compact' else 'Retain original conversion weights for future re-quantization'),
            'network': networking,
            'model_transfer': transfers,
            'model_downloader': getattr(args, 'model_downloader', 'auto'),
            'allow_model_restart': getattr(args, 'allow_model_restart', False),
            'local_models': local_reuse,
            'replace_models': sorted(replace_models, key=lambda row: row['path']),
            'model_groups': model_inventory(model_entries),
            'environment_layout': layout,
            'environment_count': len(environment_names(layout)),
            'vram_gib': vram_gib, 'ram_gib': ram_gib,
            'resource_mode': 'auto' if vram_gib is None and ram_gib is None else 'capacity-limits',
            'dependencies': dependencies,
            'model_dir': str(model_dir), 'encoder_dir': str(encoder_dir),
            'reuse_cache': str(reuse_cache) if reuse_cache else None,
            'prepared_model': prepared, 'sampling_caches': sampling_caches,
            'prepared_format': prepared_format, 'model_scale_granularity': cache_format.get('scale_granularity'),
            'model_source': 'prepared' if prepared else 'existing' if reuse_cache else 'source',
            'model_source_reason': ('Pinned slim model, matching the existing GPU precision policy' if prepared else
                                    'Reuse existing compatible cache' if reuse_cache else
                                    'Original model explicitly selected' if model_source == 'source' or getattr(args, 'rebuild_cache', False) else
                                    'No verified prebuilt artifact for this GPU scale format; preserve its original precision policy'),
            'verification': getattr(args, 'verify', 'auto'),
            'build': build,
            'kernel_install': 'Pinned Windows Triton / Sage2 wheels; actual kernels checked before readiness' if windows_target else 'Local Sage2 source build / ABI-keyed wheel cache',
            'git_install': ('Reuse detected Git' if snapshot.get('git') else
                            ('Install verified portable MinGit locally' if windows_target else
                             'Install verified portable Git from conda-forge locally') + (
                                ' (the detected Git is older than %d.%d)' % git_floor(hardware.system)
                                if snapshot.get('git_found') else '')),
            'wheel_cache': str(Path(getattr(args, 'wheel_cache', None) or saved.get('wheel_cache') or root / 'wheels').expanduser().resolve()),
            'rebuild_sage': getattr(args, 'rebuild_sage', False),
            'model_download_bytes': sum(r['bytes'] for r in files) - present - (local_reuse or {}).get('reused_bytes', 0),
            'package_download_bytes': package_download_bytes,
            'existing_model_bytes_size_matched': present, 'disks': disk_plan['disks'],
            'additional_environment_cache_safety_gib': extra,
            'preparation_ram_estimate_gib': ('Bounded hash/header verification; no transformer loaded or converted' if prepared else
                                           '4–8 GiB working set plus reclaimable source file cache; measured by setup'),
            'test_artifacts_estimate_gib': '5–8 GiB for the standard five-case suite; all outputs retained',
            'first_generation_note': 'Portable AdaLN tables follow model weights and the exact schedule, across GPUs and Torch/CUDA versions. New schedules or modulation-changing LoRAs require preparation. Existing environments stay on disk when switching.',
            'estimates_are_not_capacity_guarantees': True, 'errors': errors, 'warnings': warnings,
            'steps': ['Install isolated uv/Python and ' + ('one shared CUDA environment' if layout == 'unified' else 'two CUDA environments'),
                      'Clone the tested versions of VDN, patched Diffusers and the native H3 text-encoder library',
                      'Install verified Windows Triton / Sage2 wheels' if windows_target else 'Install a local CUDA compiler and build Sage2 for the detected GPU only',
                      'Download and verify the tested base, eight-step checkpoint and encoder weights',
                      'Prepare or verify the architecture-compatible FP8 cache',
                      'Execute small attention/linear kernel probes and save machine configuration'],
            'licenses': ['https://huggingface.co/OpenVDN/vdn-minimax-h3/blob/751739ee5b9e3ac802dca5d5111075fdaeb47885/LICENSE',
                         'https://huggingface.co/t8star/Vdn-Minimax-H3-Comfy',
                         'https://docs.nvidia.com/cuda/eula/index.html']}
    from .model_guidance import download_files
    value['download_files'] = download_files(model_entries)
    value['download_files_verified'] = all(status != 'found' for _, status in model_entries)
    if mac_target:
        from .macos_bootstrap import describe_plan
        describe_plan(value)
    else:
        value['cuda_compatibility'] = compatibility
    value['replace_models_text'] = {language: model_repair.review_lines(value['replace_models'], zh=language == 'zh')
                                    for language in ('en', 'zh')}
    return value



def display(value, ui=None, *, verbose=False):
    ui = ui or TerminalUI('Setup')
    if verbose:
        return display_details(value, ui)
    h = value['inventory']['hardware']
    usable_ram = min(h['ram_total'], h.get('cgroup_ram_limit') or h['ram_total'])
    rows = ([('GPU', h['gpu_name'] + ' · MPS'),
             ('Unified memory', '%.1f GiB / %.1f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))]
            if value.get('device_backend') == 'mps' else
            [('GPU', '%s · %.1f GiB / %.1f GiB free' % (h['gpu_name'], h['vram_total']/GiB, h['vram_free']/GiB)),
             ('RAM', '%.1f GiB / %.1f GiB available%s' % (usable_ram/GiB, min(usable_ram, h['ram_available'])/GiB,
                                                       ' · container limit' if usable_ram < h['ram_total'] else ''))])
    rows += [('Install in', value['root']),
            ('Environment', 'One shared Python environment · missing dependencies installed automatically'
             if value['environment_layout'] == 'unified' else 'Two separate Python environments · keeping your selected layout')]
    for key, default, label in (('model_dir', 'vdn', 'Model directory'), ('encoder_dir', 'encoder', 'Encoder directory')):
        if Path(value[key]) != Path(value['root']) / 'models' / default:
            rows.append((label, value[key]))
    rows.append(('Model download', '~%.1f GiB; Python / GPU packages are additional' % (value['model_download_bytes']/GiB)
                 if value['model_download_bytes'] else 'No new model files expected · verify existing files'))
    if value.get('package_download_bytes'):
        rows.append(('Package download', '~%.1f GiB to replace changed PyTorch files' % (value['package_download_bytes']/GiB)))
    from .model_repair import review_lines
    for line in review_lines(value.get('replace_models', [])):
        rows.extend((('Model repair', line['text']), ('Model repair path', line['path'])))
    if value.get('disk_mode') == 'extreme':
        rows.append(('Disk mode', 'Automatic space saver · sequential downloads · temporary package cache removed before models'))
    if value.get('local_models'):
        local = value['local_models']
        rows.append(('Reuse models', '%.1f GiB verified · %.1f GiB copied locally · source files kept' %
                     (local['reused_bytes']/GiB, local['copy_bytes']/GiB)))
    rows.append(('Download recovery', 'May restart incomplete files if resume fails; earlier data retained' if value.get('allow_model_restart')
                 else 'Retry the same source; preserve progress; pause if a restart would be required'))
    for disk in value['disks']:
        label = 'Peak disk space' if len(value['disks']) == 1 else 'Disk ' + disk['paths'][0]
        rows.append((label, '~%.1f GiB additional needed · %.1f GiB free' % (disk['needed_bytes']/GiB, disk['free_bytes']/GiB)))
    prepared = value.get('prepared_model')
    rows.append(('Storage', 'Download slim %s model · no local conversion' % prepared_precision(prepared) if prepared else
                 ('Reuse prepared %s cache' % ('ConvRot int8' if value.get('prepared_format') == 'int8_convrot' else 'FP8'))
                 if value['reuse_cache'] else 'Prepare compact FP8 model'))
    if prepared:
        rows.append(('Prepared model', prepared['repo'] + ' · ' + prepared['scale_granularity'] +
                     (' · private, authorized HF token required' if prepared.get('private') else '')))
    elif value.get('model_source') == 'source':
        rows.append(('Model source', value['model_source_reason']))
    rows.append(('Original weights', 'Not downloaded; fixed AdaLN tables included' if prepared else
                 'Remove verified conversion inputs downloaded/copied here; keep borrowed originals'
                 if value.get('storage', 'compact') == 'compact' else 'Keep original weights for future conversion'))
    setup_ram = 'Bounded model verification; no local conversion' if prepared else 'About 4–8 GiB for model preparation'
    if value.get('build'):
        setup_ram += ' · up to ~%.1f GiB for compilation' % (value['build']['estimated_peak_bytes']/GiB)
    rows.append(('Setup RAM', setup_ram))
    if value.get('model_transfer'):
        rows.append(('Model downloads', 'Native parallel · %.1f GiB process budget + disk cache managed separately' % (value['model_transfer']['ram_guard_bytes']/GiB)))
        if value.get('model_downloader') == 'xet':
            rows.append(('Download mode', 'Require HF Xet for large weights · stop on failure · curl partials retained separately'))
    limits = [value.get(key) for key in ('vram_gib', 'ram_gib')]
    rows.append(('Optimization', 'Automatic · reserves GPU and system memory' if all(v is None for v in limits)
                 else 'Capacity limits · GPU %s / RAM %s' % tuple('auto' if v is None else '%g GiB' % v for v in limits)))
    networking = value.get('network', {})
    route = ('Models via HF Xet only · package mirrors remain automatic' if value.get('model_downloader') == 'xet' and networking.get('mode') != 'official' else
             'Official sources only' if networking.get('mode') == 'official' else
             'VDN via ModelScope · retry alternatives' if network.ordered(networking, 'vdn-models')[0] == 'modelscope' else
             'Fastest available mirrors · retry alternatives')
    if prepared and prepared.get('private'):
        route = 'Prepared model via authenticated Hugging Face · other models use ranked sources'
    elif prepared and value.get('model_downloader') != 'xet' and networking.get('mode') != 'official':
        family = network.model_family(dict(repo=prepared['repo'], revision=prepared['revision']))
        source = network.ordered(networking, family)[0]
        label = {'modelscope': 'ModelScope', 'official': 'Hugging Face', 'hf-mirror': 'HF Mirror',
                 'user': 'your Hub endpoint'}.get(source, source)
        route = 'Public Edge via ' + label + ' · verified mirrors · resume retained files'
    rows.append(('Network', route
                 + (' · compare proxy / direct' if networking.get('proxy_configured') or networking.get('git_proxy_configured') else '')))
    ui.panel('FreeVideo / ' + h['system'] + ' setup', rows)
    ui.write('Space and memory are estimates. Setup checks your GPU before marking it ready.\n')
    ui.write('Model licenses: MiniMax H3, H3 text encoder.\n' if value.get('device_backend') == 'mps' else
             'Model / toolkit licenses: MiniMax H3, H3 text encoder, NVIDIA CUDA.\n')
    ui.write('Use --verbose for full details and license links, or enter d at confirmation.\n')
    for error in value['errors']:
        ui.write('BLOCKED: ' + str(error) + '\n')


def display_details(value, ui=None):
    ui = ui or TerminalUI('Setup')
    h = value['inventory']['hardware']
    rows = ([('GPU', h['gpu_name'] + ' · MPS'),
             ('Unified memory', '%.2f GiB total / %.2f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))]
            if value.get('device_backend') == 'mps' else
            [('GPU', '%s · SM %s' % (h['gpu_name'], '.'.join(map(str, h['capability'])))),
             ('VRAM', '%.2f GiB total / %.2f GiB free' % (h['vram_total']/GiB, h['vram_free']/GiB)),
             ('RAM', '%.2f GiB total / %.2f GiB available' % (h['ram_total']/GiB, h['ram_available']/GiB))])
    limits = [value.get(key) for key in ('vram_gib', 'ram_gib')]
    rows.append(('Resources', 'Automatic · current available VRAM/RAM' if all(v is None for v in limits)
                 else 'Capacity limits · VRAM %s / RAM %s' % tuple('auto' if v is None else '%g GiB' % v for v in limits)))
    resources = value.get('installation_resources') or value.get('policy_estimate')
    if resources:
        rows.append(('Installation RAM budget', '%.2f GiB · system growth reserve %.2f GiB' %
                     (resources['ram_budget_bytes']/GiB, resources['ram_system_reserve_bytes']/GiB)))
    rows.append(('Install root', value['root']))
    from .model_repair import review_lines
    for line in review_lines(value.get('replace_models', [])):
        rows.extend((('Model repair', line['text']), ('Model repair path', line['path'])))
    rows.append(('Environment', value['environment_layout'] + ' · text encoder exits before video models load'))
    rows.append(('Kernel installation', value.get('kernel_install', 'Local Sage2 build')))
    rows.append(('Git', value.get('git_install', 'Use detected Git')))
    networking = value.get('network', {})
    rows.append(('Connection', {'auto': 'Auto', 'proxy': 'Proxy only', 'direct': 'Direct only'}[
        networking.get('proxy_mode', 'auto')]))
    for name, entries in networking.get('sources', {}).items():
        selected = entries[0]
        detail = (' · %.2fs Git availability' % selected['seconds'] if name == 'git' else
                  ' · %.2f MiB/s sample' % (selected['bytes_per_second']/2**20) if selected.get('bytes_per_second')
                  else ' · connected') if selected.get('ok') else ' · unverified, downloads will retry alternatives'
        rows.append((name, selected['id'] + detail))
    for name, row in value['dependencies'].items():
        if not row['exists']:
            rows.append((name.capitalize(), 'Create isolated environment and install dependencies'))
        else:
            rows.append((name.capitalize(), 'Missing: %s · version mismatches: %s' %
                        (', '.join(row['missing']) or 'none', ', '.join(row['mismatched']) or 'none')))
    rows.append(('Model download', '%.2f GiB · existing files verified after confirmation' % (value['model_download_bytes']/GiB)))
    if value.get('package_download_bytes'):
        rows.append(('Package download', '%.2f GiB to replace changed PyTorch files' % (value['package_download_bytes']/GiB)))
    rows.append(('Storage', value.get('storage', 'compact') + ' · ' + value.get('storage_preparation', 'streamed FP8 preparation without a BF16 disk copy')))
    if value.get('prepared_model'):
        prepared = value['prepared_model']
        rows.append(('Prepared model', prepared['repo'] + '@' + prepared['revision'] + ' · ' + prepared['scale_granularity']))
        rows.append(('Access', 'Private repository; HF_TOKEN or hf auth login with an authorized account' if prepared.get('private') else 'Public repository'))
    rows.append(('Source weights', value.get('storage_cleanup', 'Retain source weights')))
    if value['reuse_cache']:
        rows.append(('Prepared cache', 'Reuse FP8 · skip original BF16/LoRA downloads and scans'))
    rows.append(('Verification', value['verification'] + ' · auto reuses unchanged model receipts; full rereads tensors'))
    if value['build']:
        rows.append(('Sage2 build', 'Up to %d compiler jobs · ~%.1f GiB RAM estimate · reusable ABI/GPU wheel cache' %
                    (value['build']['jobs'], value['build']['estimated_peak_bytes']/GiB)))
    for disk in value['disks']:
        rows.append(('Disk', '~%.1f GiB additional / %.1f GiB free · %s' %
                    (disk['needed_bytes']/GiB, disk['free_bytes']/GiB, disk['paths'][0])))
    rows += [('Preparation RAM', value['preparation_ram_estimate_gib']), ('Test outputs', value['test_artifacts_estimate_gib'])]
    rows.append(('First generation', value['first_generation_note']))
    ui.panel('FreeVideo / ' + h['system'] + ' setup plan', rows)
    print('Resource numbers are conservative estimates. The test suite measures actual usage.')
    for i, step in enumerate(value['steps'], 1):
        print('%d. %s' % (i, step))
    print('Licenses:\n' + '\n'.join(value['licenses']))
    for error in value['errors']:
        print('BLOCKED: ' + error)


def confirmed(args, value, ask=input, ui=None):
    reviewed_path = getattr(args, 'approved_plan', None)
    if reviewed_path:
        if not args.yes or not args.accept_model_license:
            raise ValueError('--approved-plan requires explicit plan/license acceptance.')
        reviewed = json.loads(Path(reviewed_path).read_text(encoding='utf-8'))
        from . import model_repair
        model_repair.reuse_names(value.get('replace_models', []), reviewed.get('replace_models', []))
        value['replace_models_text'] = {language: model_repair.review_lines(value.get('replace_models', []), zh=language == 'zh')
                                        for language in ('en', 'zh')}
        keys = ('root', 'engine_version', 'environment_layout', 'model_dir', 'encoder_dir', 'vram_gib', 'ram_gib', 'reuse_cache', 'storage', 'storage_cleanup', 'model_downloader', 'prepared_model', 'prepared_format', 'model_source', 'disk_mode', 'frontend', 'sampling_caches')
        changed = any(reviewed.get(key) != value.get(key) for key in keys)
        changed |= reviewed.get('replace_models', []) != value.get('replace_models', [])
        changed |= reviewed.get('device_backend') != value.get('device_backend')
        if value.get('device_backend') == 'mps':
            changed |= reviewed.get('inventory', {}).get('selected_device') != value['inventory']['selected_device']
        else:
            changed |= reviewed.get('inventory', {}).get('selected_gpu', {}).get('uuid') != value['inventory']['selected_gpu']['uuid']
        changed |= value['model_download_bytes'] > reviewed.get('model_download_bytes', -1)
        changed |= (value.get('package_download_bytes') or 0) > (reviewed.get('package_download_bytes') or 0)
        changed |= bool(reviewed.get('allow_model_restart')) != bool(value.get('allow_model_restart'))
        for key in ('root', 'roots', 'copy_mode', 'copy_bytes'):
            changed |= (reviewed.get('local_models') or {}).get(key) != (value.get('local_models') or {}).get(key)
        changed |= sum(disk['needed_bytes'] for disk in value['disks']) > sum(disk['needed_bytes'] for disk in reviewed.get('disks', []))
        if changed or reviewed.get('errors'):
            raise ValueError('The installation plan changed. Detect configuration again and review the new plan before installing.')
    if args.yes:
        if not args.accept_model_license:
            raise ValueError('Unattended installation requires --yes --accept-model-license.')
        return True
    if not sys.stdin.isatty():
        raise ValueError('No interactive input. Review --plan, then use --yes --accept-model-license.')
    while True:
        try:
            reply = ask('Install and accept the model/toolkit licenses? [Y/n/d] (Enter = yes, d = details): ').strip().lower()
        except EOFError:
            return False
        if reply in ('', 'y', 'yes'):
            return True
        if reply in ('n', 'no'):
            return False
        if reply in ('d', 'details'):
            display(value, ui, verbose=True)
        else:
            print('Press Enter to install, n to cancel, or d to review details.')


def download(url, path, sha, progress=None, *, networking=None, env=None):
    networking = networking or {}
    family = 'github' if url.startswith(network.SOURCES['github']['official'] + '/') else 'cuda'
    return network.download(network.urls(networking, family, url, env), path, sha, progress, network=networking, env=env, category=family)


def unpack(archive, destination):
    from .long_paths import io_path
    destination.mkdir(parents=True, exist_ok=True)
    if zipfile.is_zipfile(archive):
        with zipfile.ZipFile(archive) as zipped:
            for member in zipped.infolist():
                name = member.filename.replace('\\', '/')
                path = (destination / name).resolve()
                if (not path.is_relative_to(destination.resolve()) or ':' in name or
                        (member.external_attr >> 16) & 0o170000 == 0o120000):
                    raise ValueError('Unsafe ZIP member: ' + member.filename)
            zipped.extractall(io_path(destination))
        return
    with tarfile.open(archive) as tar:
        # Python 3.9-compatible containment checks, including link targets.
        for member in tar.getmembers():
            path = (destination / member.name).resolve()
            if not path.is_relative_to(destination.resolve()) or member.isdev() or member.isfifo():
                raise ValueError('Unsafe archive member: ' + member.name)
            if member.issym() or member.islnk():
                target = (path.parent if member.issym() else destination) / member.linkname
                if not target.resolve().is_relative_to(destination.resolve()):
                    raise ValueError('Unsafe archive link: ' + member.name)
        tar.extractall(io_path(destination))


def unpack_folder(archive, destination, name):
    """Unpack the archive's top-level folder `name` to destination/name, replacing what is there.

    A repair can find destination/name, or a file in it, replaced by a link to
    elsewhere. Checked in place, the archive's members would resolve through
    that link and be refused, and extracting would write through it. Unpack into
    a new folder instead, then replace only the link or folder at destination/name,
    never what a link points to.
    """
    destination.mkdir(parents=True, exist_ok=True)
    staging = Path(tempfile.mkdtemp(prefix='.unpack-', dir=destination))
    present = lambda path: path.is_symlink() or path.exists()
    keep = False
    try:
        unpack(archive, staging)
        unpacked = staging / name
        if unpacked.is_symlink() or not unpacked.is_dir():
            raise ValueError('Archive has no folder ' + name)
        target, previous = destination / name, staging / (name + '.previous')
        try:
            # Renaming a link moves the link itself, never what it points to.
            if present(target):
                os.replace(target, previous)
            os.replace(unpacked, target)
        except BaseException:
            # A failed or interrupted repair puts the previous uv back.
            if present(previous) and not present(target):
                try:
                    os.replace(previous, target)
                except OSError:
                    keep = True  # Rather leave it in the staging folder than delete it.
            raise
    finally:
        if not keep:
            shutil.rmtree(staging, ignore_errors=True)


def setup_task(label):
    """Describe the work independently of internal command IDs and log paths."""
    routes = {'official': 'official source', 'nju': 'Nanjing University mirror',
              'tuna': 'Tsinghua mirror', 'ghfast': 'GitHub mirror',
              'user-python': 'your Python mirror', 'user': 'your configured source'}
    # Python route retries append the route after the source.
    label = re.sub(r'-(?:direct|proxy)$', '', label)
    source = next((name for name in routes if label.endswith('-' + name)), None)
    key = label[:-(len(source) + 1)] if source else label
    for prefix in ('unified-', 'engine-', 'encoder-'):
        if key.startswith(prefix):
            key = key[len(prefix):]
            break
    tasks = {
        'release-package-cache': ('Release installation cache', 'Installed components and models are kept'),
        'space-saving-comfy': ('Prepare ComfyUI', 'Finish the environment before downloading models'),
        'python': ('Install Python', 'Download and prepare the private Python runtime'),
        'python-bootstrap-reuse': ('Use existing Python', 'Check the Python already prepared by the launcher'),
        'venv': ('Create Python environment', 'Prepare an isolated environment for FreeVideo'),
        'torch': ('Install PyTorch + CUDA', 'Download and install the GPU runtime packages'),
        'packages': ('Install engine dependencies', 'Download and install video and text encoding libraries'),
        'engine': ('Install encoder support', 'Connect the encoder to FreeVideo'),
        'vdn': ('Install model support', 'Install the verified model code'),
        'vdn-source': ('Download model code', 'Prepare model source files while runtime packages download'),
        'library-check': ('Check text encoder', 'Verify that the text encoding library loads'),
        'models': ('Download model weights', 'Download and verify the video model and text encoder'),
        'prepare': ('Optimize model storage', 'Prepare the model weights for your GPU'),
        'kernels': ('Test GPU acceleration', 'Run small checks on your GPU'),
        'storage': ('Finish model storage', 'Verify prepared weights and apply your storage choice'),
        'dependency-check': ('Check installed packages', 'Verify dependency compatibility'),
        'freeze': ('Save installed versions', 'Record versions for future diagnostics'),
        'sage2-toolchain-check': ('Check build tools', 'Verify the compiler before building GPU acceleration'),
        'sage2-build': ('Build SageAttention 2', 'Compile acceleration for your GPU · the first build takes longer'),
        'sage2-wheel-install': ('Install SageAttention 2', 'Install the prepared GPU acceleration package'),
        'sage2-windows-wheel-install': ('Install SageAttention 2', 'Install the verified Windows acceleration package'),
        'windows-runtime-check': ('Check GPU runtime', 'Verify CUDA and the Windows runtime libraries'),
        'portable-git': ('Prepare Git', 'Install the verified Git packages'),
        'portable-git-check': ('Prepare Git', 'Check the installed Git'),
        'portable-gcc': ('Prepare compiler', 'Install the verified compiler packages'),
        'portable-gcc-check': ('Prepare compiler', 'Check the installed compiler'),
    }
    title, detail = tasks.get(key, ('Prepare dependencies', 'Prepare verified source files'))
    for prefix, name in (('h3-text-encoder-', 'text encoder'), ('SageAttention-', 'SageAttention 2')):
        if key.startswith(prefix):
            title = 'Download ' + name if '-fetch' in key else 'Prepare ' + name
            detail = 'Download verified source code' if '-fetch' in key else 'Prepare source files for installation'
    if source:
        detail += ' · ' + routes[source]
    return title, detail


def reusable_kernel_receipt(path, hardware_data):
    """Return a matching successful GPU probe receipt, or ``None``.

    The receipt is deliberately tied to the same identity used by runtime
    backend selection.  A changed driver, Torch/CUDA build, installed backend,
    or engine source invalidates it and forces a fresh isolated probe.
    """
    from .hardware import Hardware, installed_backends
    from .kernel_capabilities import identity, readiness
    try:
        receipt = json.loads(Path(path).read_text(encoding='utf-8'))
        expected = identity(Hardware.from_dict(hardware_data))
        probes = receipt.get('kernel_probes')
        if (receipt.get('identity') != expected
                or sorted(receipt.get('installed_attention_packages', ())) != sorted(installed_backends())
                or not isinstance(probes, list) or not readiness(probes).get('ready')):
            return None
        return receipt
    except (OSError, ValueError, KeyError, TypeError, ImportError):
        return None


class Installer:
    def __init__(self, value, ui=None):
        self.locks = ExitStack()
        self.uv_lock = threading.Lock()
        self.uv_failure = None
        try:
            self.initialize(value, ui)
        except BaseException:
            self.locks.close()
            raise

    def initialize(self, value, ui):
        self.plan = value
        self.resources = value.get('installation_resources') or value.get('policy_estimate') or {}
        self.root = Path(value['root'])
        self.layout = value.get('environment_layout', 'unified')
        self.system = value['inventory'].get('hardware', {}).get('system', platform.system())
        self.pythons = role_pythons(self.root, self.layout, self.system)
        self.root.mkdir(parents=True, exist_ok=True)
        self.lock = self.locks.enter_context(runtime_lock(self.root / 'setup.lock', inherit=False))
        lock_path = os.environ.get('FREEVIDEO_LOCK_PATH', str(self.root / 'engine.lock'))
        self.runtime_fd = self.locks.enter_context(runtime_lock(lock_path))
        self.run_dir = self.root / 'setup-runs' / (time.strftime('%Y%m%dT%H%M%SZ', time.gmtime()) + '-' + str(os.getpid()))
        self.run_dir.mkdir(parents=True, exist_ok=False)
        save(self.run_dir / 'plan.json', value)
        previous = self.root / 'machine.json'
        saved = {}
        if previous.is_file():
            shutil.copyfile(previous, self.run_dir / 'machine.before.json')
            saved = json.loads(previous.read_text(encoding='utf-8'))
        self.saved = saved
        # Changed PyTorch files (runtime_libraries) stop torch from importing,
        # so no GPU check can pass until the torch step below reinstalls them.
        self.damaged_before = []
        if self.system != 'Darwin' and self.pythons['engine'].is_file():
            from .runtime_libraries import damaged
            if ui is not None:
                prepare_step(ui, 'Checking the environment')
            self.damaged_before = damaged(self.pythons['engine'], progress=(
                lambda done, total: prepare_step(ui, 'Checking the environment', done, total)) if ui is not None else None)
        # Moving a working installation to int8 checks the int8 kernels first
        # (execute), so a GPU that fails them keeps its configuration as it was.
        # With changed files that check cannot run; the one after installing still does.
        self.int8_check_first = (value.get('prepared_format') == 'int8_convrot' and saved.get('ready') is True
                                 and self.system != 'Darwin' and self.pythons['engine'].is_file()
                                 and not self.damaged_before)
        if not self.int8_check_first:
            self.mark_unfinished()
        self.env = dict(os.environ, FREEVIDEO_HOME=str(self.root),
            FREEVIDEO_VDN_ROOT=str(self.root / 'vendor' / 'vdn'),
            FREEVIDEO_MODEL_ROOT=value['model_dir'],
            FREEVIDEO_COMFY_ROOT=str(self.root / 'vendor' / 'h3-text-encoder'),
            FREEVIDEO_COMFY_PYTHON=str(self.pythons['encoder']),
            FREEVIDEO_LOCK_PATH=lock_path,
            PATH=str(self.pythons['engine'].parent) + os.pathsep + os.environ.get('PATH', ''),
            UV_CACHE_DIR=str(self.root / 'downloads' / 'uv-cache'),
            UV_PYTHON_INSTALL_DIR=str(self.root / 'python'), UV_LINK_MODE='hardlink',
            HF_HOME=str(self.root / 'downloads' / 'huggingface'), HF_HUB_DISABLE_TELEMETRY='1',
            HF_HUB_OFFLINE='0', TRANSFORMERS_OFFLINE='0',
            PIP_DISABLE_PIP_VERSION_CHECK='1',
            PYTHONUNBUFFERED='1', PYTHONUTF8='1', PYTHONIOENCODING='utf-8', PYTHONPATH=str(SOURCE), OMP_NUM_THREADS='4', MKL_NUM_THREADS='4')
        self.env = self.device_environment(self.env)
        self.env[LOCK_ENV] = str(self.runtime_fd)
        self.env.update(FREEVIDEO_NETWORK_PLAN=str(self.run_dir / 'plan.json'),
                        FREEVIDEO_NETWORK_EVENTS=str(self.run_dir / 'network.jsonl'))
        self.env = network.proxy_environment(self.env)
        if value.get('disk_mode') == 'extreme':
            from .install_disk import environment
            self.env = environment(self.root, self.env)
        # A folder the system code page cannot spell cannot hold what compiles kernels:
        # every step runs from the short folder, and files and receipts keep the real one.
        from . import launch_view
        if launch_view.current(self.env) is None:
            self.env = launch_view.environment_view(self.env, launch_view.for_engine(self.root))
        self.network = dict(value.get('network', {}), events_path=str(self.run_dir / 'network.jsonl'), quiet=True)
        self.state = {'status': 'running', 'steps': [], 'plan': value}
        if self.damaged_before:
            self.state['damaged_before'] = self.damaged_before
        self.state_lock = threading.Lock()
        self.cancel = threading.Event()
        self.versions = bootstrap_versions(json.loads((PACKAGE / 'bootstrap_versions.json').read_text(encoding='utf-8')), self.system)
        self.spec = json.loads((PACKAGE / 'dependencies.json').read_text(encoding='utf-8'))
        self.ui = ui or TerminalUI('Setup', plain=True)
        self.monitor_stop = threading.Event()
        self.monitor_thread = None
        self.started = time.monotonic()

    def mark_unfinished(self):
        """Persist a confirmed choice for interrupted first installs and upgrades.

        The former complete configuration is retained in machine.before.json.
        """
        value, saved = self.plan, self.saved
        save(self.root / 'machine.json', dict(saved, root=str(self.root), ready=False, setup_run=str(self.run_dir),
            storage=value.get('storage', 'compact'),
            disk_mode=value.get('disk_mode', 'normal'),
            pending_environment_layout=self.layout, model_root=value['model_dir'],
            encoder_model_root=value.get('encoder_dir', saved.get('encoder_model_root')),
            wheel_cache=value.get('wheel_cache', saved.get('wheel_cache')),
            vram_gib=value.get('vram_gib', saved.get('vram_gib')),
            ram_gib=value.get('ram_gib', saved.get('ram_gib'))))

    def device_environment(self, env):
        from .triton_compat import environment
        return environment(self.root, dict(env,
            CUDA_VISIBLE_DEVICES=self.plan['inventory']['selected_gpu']['uuid'],
            CUDA_DEVICE_ORDER='PCI_BUS_ID',
            TRITON_CACHE_DIR=str(self.root / 'kernel-cache' / 'triton'),
            CUDA_CACHE_PATH=str(self.root / 'kernel-cache' / 'cuda'),
            TORCHINDUCTOR_CACHE_DIR=str(self.root / 'kernel-cache' / 'inductor')))

    def start_monitor(self):
        from .ram import ProcessMemory
        memory = ProcessMemory()
        def sample():
            unreadable = failures = recoveries = 0
            try:
                with (self.run_dir / 'ram.jsonl').open('w', buffering=1, encoding='utf-8') as stream:
                    while not self.monitor_stop.is_set():
                        if self.plan.get('disk_mode') == 'extreme':
                            from .install_disk import check_floor
                            try:
                                check_floor([p for disk in self.plan['disks'] for p in disk['paths']])
                            except RuntimeError as error:
                                self.state['resource_guard'] = str(error)
                                self.cancel.set()
                                break
                        try:
                            row = memory.sample(os.getpid())
                        except OSError as error:
                            # The process snapshot itself can fail, too. Still
                            # obtain fresh system headroom without inventing process usage.
                            system = system_memory()
                            row = dict(guard_bytes=None,
                                system_available_bytes=system['available_bytes'],
                                system_physical_available_bytes=system['physical_available_bytes'],
                                system_commit_available_bytes=system['commit_available_bytes'],
                                memory_read_errors=[dict(error=str(error), winerror=getattr(error, 'winerror', None))])
                            if self.system == 'Linux':
                                from .hardware import cgroup_memory
                                group = cgroup_memory()
                                available = group['available_bytes']
                                reclaimable = group.get('reclaimable_available_bytes', available)
                                row.update(cgroup_memory=group,
                                    effective_available_bytes=min(system['available_bytes'],
                                        available) if available is not None else system['available_bytes'],
                                    inference_available_bytes=min(system['available_bytes'],
                                        reclaimable) if reclaimable is not None else system['available_bytes'])
                        used = memory_sample(row)
                        if used is None:
                            unreadable += 1
                            failures += 1
                            # Unreadable process usage does not prove exhaustion;
                            # retain the samples and keep checking the system floor.
                            denied = self.system == 'Windows' and _permission_limited_memory_sample(row)
                            degraded = denied or self.system != 'Windows' or unreadable >= 3
                            if degraded:
                                self.state['resource_warning'] = (
                                    'Some Windows child processes denied memory queries (WinError 5); '
                                    'continuing with the global RAM/commit floor.' if denied else
                                    'Process-tree memory is unavailable; continuing with the global RAM/commit floor.')
                                if self.state.get('monitor_status') != 'degraded':
                                    self.ui.write(self.state['resource_warning'] + '\n')
                            row = dict(row, monitor_status='degraded' if degraded else 'retrying',
                                       consecutive_unreadable=unreadable)
                        else:
                            if unreadable:
                                recoveries += 1
                            row = dict(row, monitor_status='recovered' if unreadable else 'complete',
                                       consecutive_unreadable=0)
                            unreadable = 0
                        self.state['monitor_status'] = row['monitor_status']
                        pressure = setup_memory_pressure(row, self.resources['ram_budget_bytes'], self.system)
                        row['installation_guard'] = pressure
                        stream.write(json.dumps(dict(row, elapsed_seconds=time.monotonic()-self.started, epoch_seconds=time.time())) + '\n')
                        available = pressure['available_bytes']
                        self.ui.resource = setup_memory_status(row, self.ui.verbose, system=self.system)
                        # Windows helpers can exit/change while their tree is
                        # sampled. Allow two resamples, while checking the live
                        # exhaustion floor on every attempt. The larger planning
                        # reserve is not a reason to kill a bounded download.
                        if pressure['reasons']:
                            self.state['installation_guard'] = pressure
                            self.state['resource_guard'] = setup_memory_failure(pressure)
                            self.cancel.set()
                            break
                        if available < pressure['planning_reserve_bytes']:
                            self.state['memory_headroom_warning'] = pressure
                        self.monitor_stop.wait(1)
            except BaseException as error:
                self.state['resource_guard'] = 'Installation RAM monitoring failed: ' + repr(error)
                self.cancel.set()
            finally:
                self.state['memory'] = memory.result()
                self.state['memory'].update(monitor_unreadable_samples=failures,
                    monitor_recoveries=recoveries, monitor_consecutive_unreadable=unreadable)
                if failures:
                    self.state['memory']['process_tree_guard_complete'] = False
        self.monitor_thread = threading.Thread(target=sample, name='setup-memory', daemon=True)
        self.monitor_thread.start()

    def fetch(self, url, path, sha, *, size=None, candidates=None, category=None,
              low_speed_limit=1024, max_seconds=None, cycles=2):
        key = 'download-' + path.name
        title = ('Prepare download tools' if path.name.startswith('uv') else
                 'Download GPU acceleration' if path.suffix == '.whl' else
                 'Prepare Git' if 'git' in path.name.lower() else 'Download CUDA build tools')
        self.ui.begin(key, title, detail=path.name if self.ui.verbose or candidates is not None else 'Download and verify required files')
        transfer = {}
        def source_detail():
            names = {'pypi': {'official': 'PyPI', 'tuna': 'Tsinghua mirror'},
                     'github': {'official': 'GitHub', 'ghfast': 'GitHub mirror'}}
            source = names.get(category, {}).get(transfer.get('source'), transfer.get('source', ''))
            return ' · Source: ' + source if source else ''
        def progress(done, total, speed):
            if self.cancel.is_set():
                raise RuntimeError('Installation cancelled; partial download retained.')
            rate_text = ('%.1f KiB/s' % (speed/1024) if speed < 2**20 else '%.1f MiB/s' % (speed/2**20))
            self.ui.update(key, done=done, total=total, rate=speed, unit='bytes', scope=path.name,
                activity='download', name=path.name,
                detail=(path.name + ' · ' if candidates is not None else '') +
                    ('%.1f MiB / %.1f MiB' % (done/2**20, total/2**20) if total else '%.1f MiB downloaded' % (done/2**20)) +
                    ' · ' + rate_text + source_detail())
        try:
            def feedback(row):
                transfer.update(row)
                self.ui.update(key, activity='resume' if row['action'] in ('retry', 'route-retry') else '', name=path.name,
                               detail=path.name + source_detail() + ' · ' + row['action'] +
                               (' · ' + row['reason'] if row.get('reason') else ''))
            networking = dict(self.network, event_callback=feedback)
            if candidates is None:
                download(url, path, sha, progress, networking=networking, env=self.env)
            else:
                network.download(candidates, path, sha, progress, network=networking, env=self.env,
                                 size=size, category=category or 'download',
                                 low_speed_limit=low_speed_limit, max_seconds=max_seconds, cycles=cycles)
        except BaseException:
            self.ui.end(key, success=False)
            raise
        self.ui.end(key, detail='Verified and ready')

    def ensure_uv(self):
        """Fetch uv again when security software or a cleaner removed it after it was prepared."""
        uv = Path(self.env['FREEVIDEO_UV'])
        def usable():
            try:
                return uv.is_file() and uv.stat().st_size > 0
            except OSError:
                return False
        if usable():
            return uv
        with self.uv_lock:
            # One attempt per installation: concurrent steps and later commands report the same failure.
            if self.uv_failure:
                raise RuntimeError(self.uv_failure)
            if not usable():
                self.ui.event('setup_cache', key='uv', detail='Downloading the uv tool again; it was missing')
                try:
                    self.env['FREEVIDEO_UV'] = str(self.prepare_tools())
                except BaseException:
                    self.uv_failure = 'The uv tool is missing at %s and could not be restored.' % uv
                    raise
                if not usable():
                    self.uv_failure = 'The uv tool is missing at %s and could not be restored.' % uv
                    raise RuntimeError(self.uv_failure)
        return uv

    def command(self, label, args, env=None, cwd=None):
        from .ram import ProcessMemory
        from .package_progress import PackageOutput
        if self.cancel.is_set():
            raise RuntimeError(self.state.get('resource_guard', 'Installation cancelled.'))
        from .triton_compat import temporary_environment
        env = temporary_environment(self.root, env or self.env)
        env = dict(env, FREEVIDEO_INSTALL_PROGRESS='1')
        env = with_private_compiler(self.root, env)
        args, cwd = uv_file_arguments(args, cwd)
        if args and str(args[0]) == self.env.get('FREEVIDEO_UV'):
            self.ensure_uv()
        env = uv_build_environment(args, self.root, env)
        with self.state_lock:
            index = len(self.state['steps'])
            log = self.run_dir / ('%02d-%s.log' % (index, label))
            row = {'label': label, 'command': args, 'log': str(log), 'status': 'running'}
            self.state['steps'].append(row)
            save(self.run_dir / 'status.json', self.state)
        key = str(index) + '-' + label
        title, detail = setup_task(label)
        if label == 'models' and self.plan.get('local_models'):
            title, detail = 'Reuse models / download missing files', 'Uses models already on this computer; original files stay in place'
        self.ui.begin(key, title, detail=str(log) if self.ui.verbose else detail)
        initial = ('Python downloading' if title == 'Install Python' else
                   'Environment creating' if title == 'Create Python environment' else '')
        if initial:
            self.ui.update(key, activity='note', name=initial, detail=initial)
        progress = LogProgress(log)
        parallel_tasks = set()
        models_step = label == 'models'
        build_step = label == 'sage2-build'
        def update_progress(*, final=False):
            self.ui.update(key, **progress.read(final=final))
            if progress.model_groups is not None:
                self.ui.event('models', groups=progress.model_groups)
                if models_step and getattr(self, 'model_bytes_callback', None):
                    self.model_bytes_callback(progress.model_groups)
                progress.model_groups = None
            fraction = progress.compile_fraction()
            if build_step and fraction is not None and getattr(self, 'build_callback', None):
                self.build_callback(min(fraction, .95))
            for name, details in progress.take_tasks().items():
                subkey = key + '-' + name
                label, state = details.pop('label'), details.pop('state')
                if subkey not in parallel_tasks:
                    self.ui.begin(subkey, label)
                    parallel_tasks.add(subkey)
                self.ui.update(subkey, **details)
                if state != 'running':
                    self.ui.end(subkey, success=state == 'complete', detail=details['detail'])
        tick = time.monotonic()
        memory = ProcessMemory()
        child = None
        try:
            with log.open('w', encoding='utf-8') as stream:
                with PackageOutput(row['command'], stream, env or self.env) as output:
                    child = processes.popen(row['command'], env=output.env, cwd=cwd, stdout=output.stdout, stderr=subprocess.STDOUT,
                                             start_new_session=True, supervise=True,
                                             pass_fds=() if self.runtime_fd is None else (self.runtime_fd,))
                    output.spawned()
                    try:
                        while child.poll() is None:
                            if output.error is not None:
                                raise RuntimeError('Could not retain package installation output') from output.error
                            if self.cancel.is_set():
                                raise RuntimeError('Another parallel installation step failed; cancelling this step.')
                            memory.sample(child.pid)
                            try:
                                child.wait(timeout=.5)
                            except subprocess.TimeoutExpired:
                                pass
                            update_progress()
                    except BaseException:
                        if child.poll() is None:
                            processes.stop(child)
                        raise
        except BaseException as error:
            row['error'] = repr(error)
            if child is not None and child.poll() is None:
                processes.stop(child)
            # A step stopped from outside leaves nothing else in its log to explain why.
            try:
                with log.open('a', encoding='utf-8') as stream:
                    stream.write('\nStopped: %s\n' % error)
            except OSError:
                pass
            raise
        finally:
            update_progress(final=True)
            success = child is not None and child.poll() == 0 and 'error' not in row
            for subkey in parallel_tasks:
                if self.ui.tasks[subkey]['state'] == 'running':
                    self.ui.end(subkey, success=success, detail='Ready' if success else 'Stopped; files retained')
            try:
                with self.state_lock:
                    row.update(seconds=time.monotonic()-tick, returncode=child.poll() if child else None, memory=memory.result(),
                               status='complete' if success else 'failed')
                    save(self.run_dir / 'status.json', self.state)
            finally:
                self.ui.end(key, success=success, detail=(getattr(progress, 'last_notice', None) or 'Log: ' + str(log))
                            if self.ui.verbose or not success else 'Ready')
        if child.returncode:
            from .failure_details import setup_command_failure, environment_python_removed
            report = args[args.index('--out') + 1] if '--out' in args[:-1] else None
            raise RuntimeError(environment_python_removed(args, getattr(self, 'pythons', {}).values())
                               + setup_command_failure(label, log, child.returncode, report=report))
        return log

    def component_tasks(self, uv):
        """Dependencies, not serial UI stages, determine when work can start."""
        tasks = {}
        def task(name, run, after=(), writes=()):
            tasks[name] = dict(run=run, after=tuple(after), writes=tuple(writes))
        task('python', lambda: self.python_install(uv))
        task('git', self.install_git)
        # This entry imports only stdlib engine code from the bootstrap Python.
        # It can fetch the exact source trees while large Torch wheels download.
        task('vdn-source', lambda: self.command('vdn-source', [sys.executable, '-c',
            'from freevideo_engine.install import install; install()']), after=('git',))
        task('encoder-source', lambda: self.clone('h3-text-encoder',
            self.spec['encoder']['comfy_url'], self.spec['encoder']['comfy_commit'],
            sparse=['/comfy/', '/utils/', '/folder_paths.py', '/node_helpers.py', '/LICENSE']), after=('git',))
        pythons = {}
        for name in environment_names(self.layout):
            spec = ENVIRONMENTS[name]
            venv = self.root / 'envs' / name
            python = venv_python(venv, self.system)
            pythons[name] = python
            writer = ('environment:' + name,)
            def environment(folder=venv, executable=python, label=name):
                if executable.exists() and environment_seeded(folder):
                    return None
                from .failure_details import environment_python_removed, file_in_use
                for wait in (*ENVIRONMENT_BUSY_WAITS, None):
                    command = [uv, 'venv', '--seed', '--python', self.versions['python']]
                    # The Python file came back (restored from quarantine) without
                    # the seed packages: keep it and add them. Without the file, the
                    # folder is a leftover that uv replaces.
                    if executable.exists():
                        command.append('--allow-existing')
                    elif folder.exists():
                        command.append('--clear')
                    try:
                        return self.packages(label + '-venv', [*command, folder])
                    except RuntimeError as error:
                        # Another program (usually security software scanning the
                        # Python file just unpacked) held it open while uv copied it.
                        if wait is not None and file_in_use(error) and not self.cancel.is_set():
                            self.ui.write('A file is in use by another program; trying again in %d s.\n' % wait)
                            if not self.cancel.wait(wait):
                                continue
                            raise
                        # uv failed while the new interpreter was disappearing.
                        removed = '' if executable.exists() else environment_python_removed([executable], [executable])
                        if not removed:
                            raise
                        raise RuntimeError(removed + str(error)) from error
            task(name + '-venv', environment, ('python',), writer)
            command = [uv, 'pip', 'install', '--python', python, *spec['torch'], '-c', constraints_file(name, self.system)]
            family = 'torch-' + spec['cuda'] + '-' + spec['torch'][0].split('==')[1]
            def torch_packages(label=name, argv=command, group=family, role=spec, executable=python):
                if self.system == 'Windows':
                    from .torch_download import install
                    def check():
                        if self.cancel.is_set():
                            raise RuntimeError('Installation cancelled; partial download retained.')
                        if self.plan.get('disk_mode') == 'extreme':
                            from .install_disk import check_floor
                            check_floor((self.root,))
                    if install(uv, executable, role['torch'], role['cuda'], root=self.root,
                               networking=self.network, env=self.env, ui=self.ui,
                               run=lambda args, env: self.command(label + '-torch', args, env=env),
                               constraints=['-c', constraints_file(label, self.system)], check=check,
                               reinstall=self.missing_files(executable, label, gpu=True, wheels=role)):
                        return
                from .runtime_libraries import damaged, reinstall_arguments
                fresh = sorted(set(self.check_runtime_libraries(executable, label)) | set(self.missing_files(executable, label, gpu=True)))
                result = self.packages(label + '-torch', [*argv[:5], *reinstall_arguments(fresh), *argv[5:]], group)
                # Files linked from a changed uv cache arrive with a new environment.
                if not fresh:
                    changed = self.check_runtime_libraries(executable, label)
                    if changed:
                        result = self.packages(label + '-torch', [*argv[:5], *reinstall_arguments(changed), *argv[5:]], group)
                return result
            task(name + '-torch', torch_packages,
                 (name + '-venv',), writer)
        name = 'unified' if self.layout == 'unified' else 'engine'
        python, encoder_python = self.pythons['engine'], self.pythons['encoder']
        command = [uv, 'pip', 'install', '--python', python, '-e', str(SOURCE) + '[runtime]',
                   '-c', constraints_file(name, self.system), 'pip', 'ninja', 'packaging', 'wheel', 'setuptools']
        if self.layout == 'unified':
            command += ['-r', SOURCE / 'constraints/encoder-runtime.txt']
        task('runtime', lambda: self.packages(name + '-packages', self.repairing(command, python, name)),
             (name + '-torch',), ('environment:' + name,))
        # Enqueue downloads as soon as their SDKs exist, before waiting for
        # source setup, encoder checks or acceleration compilation.
        task('models', lambda: self.command('models', [python, '-m', 'freevideo_engine.provision',
            '--plan', self.run_dir / 'plan.json']), ('runtime',))
        task('vdn-install', lambda: self.command('vdn', [python, '-m', 'freevideo_engine', 'setup', '--install-packages']),
             ('runtime', 'vdn-source'), ('environment:' + name,))
        encoder_after = 'runtime'
        if self.layout == 'dual':
            def encoder_packages():
                self.packages('encoder-packages', self.repairing([uv, 'pip', 'install', '--python', encoder_python,
                    '-r', SOURCE / 'constraints/encoder-runtime.txt', '-c', constraints_file('encoder', self.system)],
                    encoder_python, 'encoder'))
                self.packages('encoder-engine', [uv, 'pip', 'install', '--python', encoder_python, '--no-deps', '-e', SOURCE])
            task('encoder-runtime', encoder_packages, ('encoder-torch',), ('environment:encoder',))
            encoder_after = 'encoder-runtime'
        comfy = self.root / 'vendor' / 'h3-text-encoder'
        task('encoder-check', lambda: self.command('encoder-library-check', [encoder_python, '-m',
            'freevideo_engine.encode_worker', '--comfy-root', comfy, '--check-library']),
             (encoder_after, 'encoder-source'), ('environment:unified' if self.layout == 'unified' else 'environment:encoder',))
        if self.system == 'Windows':
            task('windows-check', lambda: self.command('windows-runtime-check', [python, '-c',
                'import torch,triton,safetensors,comfy_kitchen,comfy_aimdo; '
                'assert torch.cuda.is_available(), "CUDA unavailable; check NVIDIA driver and Windows DLL errors above"; '
                'print("Windows runtime imports passed; GPU kernel probes follow")']), ('runtime',), ('environment:' + name,))
        overlap = (self.plan.get('model_transfer') or {}).get('overlap_build', True)
        # Linux builds SageAttention from a Git checkout.
        task('sage', lambda: self.install_sage_optional(uv, python), ('runtime', 'git') if overlap else ('runtime', 'git', 'models'),
             ('environment:' + name,))
        if self.plan.get('disk_mode') == 'extreme':
            # Finish all environments before models occupy most of the disk.
            # In particular retain the uv cache until ComfyUI has reused it.
            tasks['sage']['after'] = ('runtime', 'git')
            prerequisites = tuple(key for key in tasks if key != 'models')
            frontend = self.plan.get('frontend') or {}
            if frontend.get('separate'):
                task('frontend', lambda: self.command('space-saving-comfy',
                    [python, '-m', 'freevideo_engine.comfy_host', '--root', self.root,
                     '--comfy', frontend['root'], '--setup-plan', self.run_dir / 'plan.json']), prerequisites)
                prerequisites = ('frontend',)
            task('package-cache', lambda: self.release_package_cache(uv), prerequisites)
            tasks['models']['after'] = ('package-cache',)
        return tasks, pythons, comfy

    def missing_files(self, python, role, *, gpu=None, wheels=None):
        """Pinned packages of an environment whose files are gone (runtime_libraries.package_files).

        gpu=True keeps the PyTorch family, which is installed from the GPU wheels (and only
        those of `wheels`, an environment's spec, when given); gpu=False keeps the rest."""
        from .runtime_libraries import gpu_family, missing_packages, normalize_name
        try:
            names = missing_packages(python, constraints_file(role, self.system))
        except ValueError:
            return []
        if gpu is not None:
            names = [name for name in names if gpu_family(name) == gpu]
        if wheels is not None:
            from .torch_download import select
            catalog = {normalize_name(row['package']) for row in select(wheels['torch'], wheels['cuda']) or []}
            names = [name for name in names if normalize_name(name) in catalog]
        return names

    def repairing(self, argv, python, role):
        """An install command that also replaces the pinned packages whose files are gone.

        Installing the pinned version again does nothing when uv finds it installed,
        whatever state its files are in. The PyTorch family is replaced in its own step."""
        from .runtime_libraries import reinstall_arguments
        names = self.missing_files(python, role, gpu=False)
        return [*argv[:5], *reinstall_arguments(names), *argv[5:]] if names else argv

    def check_runtime_libraries(self, python, role):
        from .runtime_libraries import damaged
        key = role + '-runtime-libraries'
        self.ui.begin(key, 'Runtime libraries verifying')
        def progress(done, total):
            self.ui.update(key, activity='count', name='Runtime libraries verifying',
                           detail='Runtime libraries verifying', done=done, total=total, unit='items')
        try:
            return damaged(python, progress=progress)
        finally:
            self.ui.end(key)

    def release_package_cache(self, uv):
        cache = self.root / 'downloads' / 'uv-cache'
        if cache.is_symlink() or not cache.resolve().is_relative_to(self.root.resolve()):
            raise ValueError('The installation cache points outside this FreeVideo folder; '
                             'space-saving cleanup stopped without removing it.')
        # Use uv's lock-aware cleanup; never unlink its internal files ourselves.
        result = self.command('release-package-cache', [uv, 'cache', 'clean', '--cache-dir', cache])
        from .torch_download import release_cache
        release_cache(self.root)
        return result

    def clone(self, name, url, commit, sparse=None):
        return network.clone(self.root / 'vendor' / name, url, commit, sparse=sparse, run=self.command,
                             network=self.network, env=self.env)

    @contextmanager
    def download_notice(self, key):
        """Keep the patient-round notice visible across command heartbeats."""
        active = False

        def notice(message):
            nonlocal active
            self.ui.write(message + '\n')
            active = True
            self.ui.event('progress', key=key, label='Download', detail=message)

        try:
            yield notice
        finally:
            if active:
                self.ui.event('progress', key=key, label='Download', detail='', state='complete')

    def packages(self, label, args, family='pypi'):
        with self.download_notice('download-patient-' + label) as notice:
            return network.package_command(self.network, family,
                lambda env, source: self.command(label if source == 'official' else label + '-' + source, args, env=env),
                self.env, notice=notice)

    def python_install(self, uv):
        from .system import bootstrap_root
        prepared = bootstrap_root(self.root) / 'python'
        current = Path(self.env['UV_PYTHON_INSTALL_DIR'])
        # A from-zero launcher already installed this exact Python. Reuse its
        # base interpreter when creating the single compute venv; do not download
        # and unpack another copy. Existing installations keep their own base.
        if prepared.is_dir() and not any(current.glob('cpython-' + self.versions['python'] + '-*')):
            env = dict(self.env, UV_PYTHON_INSTALL_DIR=str(prepared))
            uv = self.ensure_uv() if str(uv) == self.env.get('FREEVIDEO_UV') else uv
            found = subprocess_output.run_external([str(uv), '--no-config', 'python', 'find', '--managed-python',
                                    '--no-python-downloads', self.versions['python']],
                                   env=env, capture_output=True, timeout=30)
            if found.returncode == 0:
                candidate = Path(found.stdout.strip())
                if candidate.is_file() and candidate.resolve().is_relative_to(prepared.resolve()):
                    check = subprocess_output.run_python([str(candidate), '-I', '-B', '-c',
                        'import platform; print(platform.python_version())'], capture_output=True, timeout=30)
                    if check.returncode == 0 and check.stdout.strip() == self.versions['python']:
                        self.env['UV_PYTHON_INSTALL_DIR'] = str(prepared)
                        # -I ignores PYTHONIOENCODING: without -X utf8 a path the
                        # system code page cannot spell fails the print.
                        self.command('python-bootstrap-reuse', subprocess_output.python_command([candidate, '-I', '-B', '-c',
                                     'import sys; print("Reusing verified bootstrap Python: " + sys.executable)']))
                        return
        custom = self.env.get('UV_PYTHON_INSTALL_MIRROR') if self.network.get('mode') != 'official' else None
        isolation = ['--no-bin', '--no-registry']
        def attempt(source, route, retry_mode):
            env = network.download_environment(
                network.route_environment(self.network, 'github', source, self.env, route), retry_mode)
            env['UV_PYTHON_INSTALL_MIRROR'] = custom if source == 'user-python' else network.source_url('github', source, self.env) + '/astral-sh/python-build-standalone/releases/download'
            return self.command('python-' + source + '-' + route,
                                [uv, 'python', 'install', *isolation, self.versions['python']], env=env)
        try:
            with self.download_notice('download-patient-python') as notice:
                return network.download_command(self.network, 'github', attempt, self.env, category='python',
                                                extra_sources=['user-python'] if custom else [], notice=notice)
        except network.PackageSourcesError as error:
            failure = RuntimeError('Python download failed on every route; see retained logs'
                                   + network.sources_text(error.attempts))
            failure.package_attempts = error.attempts
            raise failure from error

    def install_sage_optional(self, uv, python):
        """Sage2 is an optional speed-up: where FreeVideo's own compiler builds it, a failure leaves it out."""
        try:
            return self.install_sage(uv, python)
        except Exception as error:
            if (self.system == 'Windows' or self.cancel.is_set()
                    or shutil.which('g++', path=self.env['PATH'])):
                raise
            self.ui.write('Sage2 could not be built (%s); continuing without it.\n' % type(error).__name__)
            return None

    def install_sage(self, uv, python):
        if self.system == 'Windows':
            return self.install_sage_windows(uv, python)
        code = ('import json,platform,sys,torch; print(json.dumps(dict('
                'python="cp"+str(sys.version_info.major)+str(sys.version_info.minor), '
                'torch=str(torch.__version__),cuda=torch.version.cuda,cxx11_abi=torch.compiled_with_cxx11_abi(), '
                'machine=platform.machine(),glibc=platform.libc_ver())))')
        identity = json.loads(subprocess_output.output_python([str(python), '-c', code], env=self.env))
        compiler = self.host_compiler(identity['cuda'])
        identity.update(arch='.'.join(map(str, self.plan['inventory']['hardware']['capability'])),
                        source=self.spec['sageattention']['commit'], compiler=compiler['identity'])
        wheel_dir = Path(self.plan['wheel_cache']) / wheel_key(identity)
        manifest = wheel_dir / 'manifest.json'
        record = json.loads(manifest.read_text(encoding='utf-8')) if manifest.is_file() else None
        cached = False
        if record and not self.plan['rebuild_sage']:
            filename = record['filename']
            if Path(filename).name != filename or not filename.endswith('.whl'):
                raise ValueError('Invalid wheel cache filename')
            wheel = wheel_dir / filename
            cached = record['identity'] == identity and wheel.is_file() and digest(wheel) == record['sha256']
        if not cached:
            # Keep old wheels/build objects when forcing a fresh measured build.
            if wheel_dir.exists():
                wheel_dir.rename(wheel_dir.with_name(wheel_dir.name + '.previous-' + self.run_dir.name))
            wheel_dir.mkdir(parents=True)
            toolkit = self.install_toolkit(identity['cuda'])
            sage = self.clone('SageAttention', self.spec['sageattention']['url'], self.spec['sageattention']['commit'])
            stamp = sage / '.freevideo-build.json'
            previous_identity = json.loads(stamp.read_text(encoding='utf-8')) if stamp.is_file() else None
            if (self.plan['rebuild_sage'] or previous_identity != identity) and (sage / 'build').exists():
                (sage / 'build').rename(sage / ('build.previous-' + self.run_dir.name))
            save(stamp, identity)
            header_code = ('from pathlib import Path; import site; '
                          'print(":".join(str(p) for s in site.getsitepackages() for p in (Path(s)/"nvidia").glob("*/include")))')
            headers = subprocess_output.output_python([str(python), '-c', header_code], env=self.env).strip()
            build = self.plan['build']
            build_env = dict(self.env, CUDA_HOME=str(toolkit), PATH=str(toolkit / 'bin') + os.pathsep + self.env['PATH'],
                CPATH=headers, TORCH_CUDA_ARCH_LIST=identity['arch'], MAX_JOBS=str(build['jobs']),
                EXT_PARALLEL='1', NVCC_APPEND_FLAGS='--threads=' + str(build['nvcc_threads']))
            headers_conflict = compiler['env'] is not None and self.host_headers_conflict(toolkit, dict(build_env, **compiler['env']))
            if headers_conflict:
                compiler = dict(compiler, env=None, built_with=pinned_compiler_identity())
            build_env.update(compiler['env'] if compiler['env'] is not None else self.install_compiler_linux())
            if compiler['env'] is None:
                # The private compiler is newer than an older system's libstdc++, which the Python process loads first.
                build_env['LDFLAGS'] = (build_env.get('LDFLAGS', '') + ' -static-libstdc++ -static-libgcc').strip()
            self.command('sage2-toolchain-check', [python, '-c',
                'from torch.utils.cpp_extension import is_ninja_available; '
                'assert is_ninja_available(), "Ninja must be visible in the build PATH; serial fallback is refused"'], env=build_env)
            self.command('sage2-build', [python, '-m', 'pip', 'wheel', '--verbose', '--no-build-isolation', '--no-deps',
                         '--wheel-dir', wheel_dir, sage], env=build_env)
            wheels = list(wheel_dir.glob('*.whl'))
            if len(wheels) != 1:
                raise ValueError('Expected one locally built Sage2 wheel')
            wheel = wheels[0]
            record = {'identity': identity, 'filename': wheel.name, 'sha256': digest(wheel),
                      'bytes': wheel.stat().st_size, 'build_run': str(self.run_dir), 'kernel_validation': 'pending'}
            if headers_conflict:
                record.update(headers='private sysroot', built_with=compiler['built_with'])
            save(manifest, record)
        # Install from the verified wheel path, avoiding architecture-blind source caches.
        self.command('sage2-wheel-install', [uv, 'pip', 'install', '--python', python, '--no-deps',
                                           '--reinstall-package', 'sageattention', wheel])
        save(self.run_dir / 'sage-wheel.json', dict(record, reused=cached, cache=str(wheel_dir)))
        return manifest

    def host_headers_conflict(self, toolkit, env):
        """Whether the system's C library headers clash with the toolkit's, so only a private sysroot can build Sage2.

        A new glibc (rsqrt from 2.42, sinpi and cospi from 2.41) declares math functions noexcept, which
        the toolkit declares without. Every compiler that reads the system headers fails on it, whatever its
        version, so a small CUDA file that includes <cmath> is compiled with the chosen compiler first. Any
        other outcome, including a probe that cannot run, leaves the build as it was.
        """
        probe = self.run_dir / 'host-headers-probe.cu'
        probe.write_text('#include <cmath>\n__global__ void probe(double* p) { p[0] = rsqrt(p[0]); }\n', encoding='utf-8')
        command = [str(toolkit / 'bin' / 'nvcc'), '-std=c++17', '-cuda', str(probe), '-o', str(probe.with_suffix('.cpp'))]
        if env.get('CC'):
            command[1:1] = ['-ccbin', env['CC']]
        try:
            output, conflict = subprocess_output.output_external(command, env=env, stderr=subprocess.STDOUT, timeout=300), False
        except subprocess.CalledProcessError as error:
            output = error.output if isinstance(error.output, str) else str(error.output or '')
            conflict = 'exception specification is incompatible' in output
        except (OSError, subprocess.SubprocessError) as error:
            output, conflict = str(error), False
        save(self.run_dir / 'sage-host-headers.json', {'conflict': conflict, 'compiler': env.get('CC', 'g++'), 'glibc': list(platform.libc_ver()),
                                                      'output': output[-4000:]})
        return conflict

    def host_compiler(self, cuda):
        """The compiler pair Sage is built with: the system's, a versioned one beside it, or FreeVideo's own.

        `env` is empty when the system compiler is used; `identity` names the compiler in the wheel cache key.
        A portable compiler is only installed when a build is needed (see install_compiler_linux).
        """
        spec = json.loads((PACKAGE / 'gcc_linux.json').read_text(encoding='utf-8'))
        below = spec['host_compiler_below'].get(cuda)
        # Without any system g++, FreeVideo's own compiler builds Sage2.
        if not shutil.which('g++', path=self.env['PATH']):
            choice = None
        else:
            choice = host_compiler_choice(below, self.env['PATH'], self.env) if below else {}
        if choice is None:
            return {'env': None, 'identity': pinned_compiler_identity(spec)}
        cxx = choice.get('CXX', 'g++')
        return {'env': choice, 'identity': subprocess_output.output_external([cxx, '--version']).splitlines()[0]}

    def install_compiler_linux(self):
        """GCC from conda-forge, pinned by package hashes, for a system compiler newer than the toolkit accepts."""
        spec = json.loads((PACKAGE / 'gcc_linux.json').read_text(encoding='utf-8'))
        prefix = self.root / 'tools' / ('gcc-' + spec['version'])
        triple = 'x86_64-conda-linux-gnu'
        compilers = {'CC': prefix / 'bin' / (triple + '-gcc'), 'CXX': prefix / 'bin' / (triple + '-g++')}
        receipt, content = prefix / '.freevideo-gcc.json', {k: spec[k] for k in ('version', 'packages')}
        if not (receipt.is_file() and json.loads(receipt.read_text(encoding='utf-8')) == content
                and all(path.is_file() for path in compilers.values())):
            micromamba, packages = self.fetch_conda_lock(spec, 'gcc-linux', 'compiler')
            if prefix.is_symlink():
                prefix.unlink()
            elif prefix.exists():
                shutil.rmtree(prefix)
            explicit = self.root / 'downloads' / 'gcc-linux' / 'explicit.txt'
            explicit.write_text('@EXPLICIT\n' + ''.join(path.resolve().as_uri() + '\n' for path in packages), encoding='utf-8')
            cache = self.root / 'tools' / 'micromamba-root'
            env = {k: v for k, v in self.env.items() if not k.upper().startswith(('CONDA', 'MAMBA'))}
            self.command('portable-gcc', [micromamba, 'create', '--yes', '--no-rc', '--offline',
                                          '--root-prefix', cache, '--prefix', prefix, '--file', explicit], env=env)
            save(receipt, content)
            shutil.rmtree(cache, ignore_errors=True)
            shutil.rmtree(explicit.parent, ignore_errors=True)
            micromamba.unlink(missing_ok=True)
        self.command('portable-gcc-check', [compilers['CXX'], '--version'])
        # The same compiler under its plain names, for tools that look for gcc (Triton builds its launcher with it).
        links = self.root / 'tools' / 'gcc-bin'
        links.mkdir(parents=True, exist_ok=True)
        for name, target in (('gcc', compilers['CC']), ('cc', compilers['CC']), ('g++', compilers['CXX'])):
            if not (links / name).is_symlink() or Path(os.readlink(links / name)) != target:
                (links / name).unlink(missing_ok=True)
                (links / name).symlink_to(target)
        return {key: str(path) for key, path in compilers.items()}

    def install_sage_windows(self, uv, python):
        spec = self.versions['windows']['sageattention']
        directory = Path(self.plan['wheel_cache']) / 'windows-sage2' / spec['sha256'][:16]
        wheel = directory / unquote(urlsplit(spec['url']).path.rsplit('/', 1)[-1])
        reused = wheel.is_file()
        self.fetch(spec['url'], wheel, spec['sha256'])
        self.command('sage2-windows-wheel-install', [uv, 'pip', 'install', '--python', python,
                     '--no-deps', '--reinstall-package', 'sageattention', wheel])
        record = dict(spec, filename=wheel.name, reused=reused, cache=str(directory),
                      build_run=str(self.run_dir), kernel_validation='pending',
                      architecture=self.plan['inventory']['hardware']['capability'])
        manifest = directory / 'manifest.json'
        save(manifest, record)
        save(self.run_dir / 'sage-wheel.json', record)
        return manifest

    def install_git(self):
        if self.system == 'Windows':
            self.install_git_windows()
        elif self.system == 'Linux' and not usable_git(self.env['PATH'], self.env):
            self.install_git_linux()

    def install_git_linux(self):
        """Git from conda-forge, pinned by package hashes, when the system has none new enough."""
        self.install_git_conda('git_linux.json', 'git-linux', self.fetch_git_linux)

    def install_git_conda(self, filename, folder, fetch, wrapper=False):
        spec = json.loads((PACKAGE / filename).read_text(encoding='utf-8'))
        prefix = self.root / 'tools' / ('git-' + spec['version'])
        executable = prefix / 'bin' / 'git'
        receipt, content = prefix / '.freevideo-git.json', {k: spec[k] for k in ('version', 'packages')}
        if not (receipt.is_file() and json.loads(receipt.read_text(encoding='utf-8')) == content and executable.is_file()):
            micromamba, packages = fetch(spec)
            # conda writes the prefix into the installed files, so the
            # environment is created in place; an interrupted one is replaced.
            if prefix.is_symlink():
                prefix.unlink()
            elif prefix.exists():
                shutil.rmtree(prefix)
            explicit = self.root / 'downloads' / folder / 'explicit.txt'
            explicit.write_text('@EXPLICIT\n' + ''.join(path.resolve().as_uri() + '\n' for path in packages), encoding='utf-8')
            cache = self.root / 'tools' / 'micromamba-root'
            env = {k: v for k, v in self.env.items() if not k.upper().startswith(('CONDA', 'MAMBA'))}
            self.command('portable-git', [micromamba, 'create', '--yes', '--no-rc', '--offline',
                                          '--root-prefix', cache, '--prefix', prefix, '--file', explicit], env=env)
            save(receipt, content)
            # Only the environment is kept; a damaged one is downloaded again.
            shutil.rmtree(cache, ignore_errors=True)
            shutil.rmtree(explicit.parent, ignore_errors=True)
            micromamba.unlink(missing_ok=True)
        # PATH, here and in machine.json for ComfyUI, gains only `git`, not
        # the other tools of the environment.
        links = self.root / 'tools' / 'git-bin'
        links.mkdir(parents=True, exist_ok=True)
        if wrapper:
            # macOS resolves @loader_path from the path it was started by, so a script
            # starts the real executable instead of a link to it.
            text = '#!/bin/sh\nexec %s "$@"\n' % shlex.quote(str(executable))
            if not (links / 'git').is_file() or (links / 'git').is_symlink() or (links / 'git').read_text(encoding='utf-8') != text:
                (links / 'git').unlink(missing_ok=True)
                (links / 'git').write_text(text, encoding='utf-8')
                (links / 'git').chmod(0o755)
        elif not (links / 'git').is_symlink() or Path(os.readlink(links / 'git')) != executable:
            (links / 'git').unlink(missing_ok=True)
            (links / 'git').symlink_to(executable)
        self.env['PATH'] = str(links) + os.pathsep + self.env['PATH']
        self.command('portable-git-check', [links / 'git', '--version'])
        self.env['FREEVIDEO_GIT'] = str(links / 'git')

    def fetch_git_linux(self, spec):
        """micromamba and the locked packages, verified by SHA-256, as one step."""
        return self.fetch_conda_lock(spec, 'git-linux', 'Git')

    def fetch_conda_lock(self, spec, folder, label):
        directory = self.root / 'downloads' / folder
        tool = spec['micromamba']
        micromamba = self.root / 'tools' / ('micromamba-' + tool['version'])
        channels = spec['channels']
        # Mainland mirrors first when the measured PyPI ranking prefers one.
        mirrors = [n for n in channels if n != 'official']
        names = (mirrors + ['official'] if network.ordered(self.network, 'pypi')[0] in mirrors else
                 ['official'] + mirrors)
        rows = [(micromamba, network.urls(self.network, 'github', tool['url'], self.env), tool)]
        rows += [(directory / row['path'].split('/')[-1], [(n, channels[n] + '/' + row['path']) for n in names], row)
                 for row in spec['packages']]
        total = sum(row['bytes'] for _, _, row in rows)
        key = 'download-' + folder
        self.ui.begin(key, 'Prepare ' + label, detail='Download and verify %s %s' % (label, spec['version']))
        done = 0
        try:
            for path, candidates, row in rows:
                def progress(current, size, speed, before=done):
                    if self.cancel.is_set():
                        raise RuntimeError('Installation cancelled; partial download retained.')
                    # One step for micromamba and the packages: the line names the tool with the step's total.
                    self.ui.update(key, done=before + current, total=total, rate=speed, unit='bytes', scope=label.lower(),
                                   activity='download', name=label,
                                   detail='%.1f MiB / %.1f MiB' % ((before + current) / 2**20, total / 2**20))
                def feedback(event):
                    if event['action'] in ('retry', 'route-retry'):
                        self.ui.update(key, activity='resume', name=label)
                network.download(candidates, path, row['sha256'], progress,
                                 network=dict(self.network, quiet=True, event_callback=feedback),
                                 env=self.env, size=row['bytes'], category='github' if path == micromamba else 'download')
                done += row['bytes']
        except BaseException:
            self.ui.end(key, success=False)
            raise
        micromamba.chmod(0o755)
        self.ui.end(key, detail='Verified and ready')
        return micromamba, [path for path, _, _ in rows[1:]]

    def install_git_windows(self):
        # An older Git on PATH, or one whose HTTPS helper cannot load libcurl, cannot
        # fetch the pinned sources; use the portable one.
        found = usable_git(self.env['PATH'], self.env)
        if found and network.git_https_ready(found, self.env):
            return
        spec = self.versions['windows']['git']
        archive = self.root / 'downloads' / ('MinGit-' + spec['version'] + '.zip')
        self.fetch(spec['url'], archive, spec['sha256'])
        directory = self.root / 'tools' / ('git-' + spec['version'])
        unpack(archive, directory)
        executable = directory / spec['executable']
        if not executable.is_file():
            raise RuntimeError('Portable Git archive is incomplete: ' + str(executable))
        self.env['PATH'] = str(executable.parent) + os.pathsep + self.env['PATH']
        self.command('portable-git-check', [executable, '--version'])
        self.env['FREEVIDEO_GIT'] = str(executable)

    def install_toolkit(self, cuda):
        spec = self.versions['cuda_toolkits'][cuda]
        toolkit = self.root / 'tools' / ('cuda-' + cuda)
        receipt = toolkit / '.freevideo-toolkit.json'
        complete = lambda: all((toolkit / name).is_file() and (toolkit / name).stat().st_size
                               for name in spec['required_files'])
        if receipt.is_file() and json.loads(receipt.read_text(encoding='utf-8')) == spec and complete():
            return toolkit
        # CUDA 13 splits CRT and NVVM into additional archives. An nvcc binary
        # alone is not a usable compiler, especially after interrupted setup.
        toolkit.mkdir(parents=True, exist_ok=True)
        for component in spec['components'].values():
            archive = self.root / 'downloads' / Path(component['relative_path']).name
            self.fetch(self.versions['cuda_redist_base'] + component['relative_path'], archive, component['sha256'])
            unpack(archive, self.root / 'tools' / 'cuda-components')
            unpacked = self.root / 'tools' / 'cuda-components' / archive.name.removesuffix('.tar.xz')
            shutil.copytree(unpacked, toolkit, dirs_exist_ok=True, symlinks=True)
        if not (toolkit / 'lib64').exists() and not (toolkit / 'lib64').is_symlink():
            (toolkit / 'lib64').symlink_to('lib', target_is_directory=True)
        if not complete():
            raise RuntimeError('CUDA toolkit is incomplete: ' + str(toolkit))
        save(receipt, spec)
        return toolkit

    def machine_configuration(self, python, encoder_python, comfy, prepared):
        """The complete machine.json written once every setup step has passed."""
        return {'schema_version': 1, 'root': str(self.root), 'source': str(SOURCE),
            'storage': self.plan.get('storage', 'compact'),
            'disk_mode': self.plan.get('disk_mode', 'normal'),
            'environment_layout': self.layout,
            'system': self.system, 'engine_version': __version__,
            'git': self.env.get('FREEVIDEO_GIT') or shutil.which('git', path=self.env['PATH']),
            'platform_validation': 'Local dependency and small GPU probes passed; full consumer-GPU validation comes from user test reports.',
            'kernel_capabilities': str(self.root / 'kernel-capabilities.json'),
            'python': str(python), 'comfy_python': str(encoder_python), 'comfy_root': str(comfy),
            'vdn_root': str(self.root / 'vendor' / 'vdn'), 'model_root': self.plan['model_dir'],
            'encoder_model_root': self.plan['encoder_dir'], 'wheel_cache': self.plan['wheel_cache'],
            'base': str(Path(self.plan['model_dir']) / 'h3-base'),
            'checkpoint': str(Path(self.plan['model_dir']) / 'stage-dmd-step-250'),
            'cache': json.loads(prepared.read_text(encoding='utf-8'))['cache'],
            'encoder': self.spec['models']['encoder_file'].split('/')[-1],
            'model_paths': str(self.root / 'encoder-paths.yaml'),
            **self.device_configuration(),
            'vram_gib': self.plan.get('vram_gib'), 'ram_gib': self.plan.get('ram_gib'),
            'model_revision': self.spec['models']['vdn_revision'],
            'prepared_format': self.plan.get('prepared_format', 'fp8'),
            'setup_run': str(self.run_dir), 'ready': True}

    def device_configuration(self):
        return {'gpu_uuid': self.plan['inventory']['selected_gpu']['uuid']}

    def check_kernels(self, python, kernel_report):
        # Kernel probes execute real CUDA work and take roughly a minute on a
        # consumer GPU.  A completed receipt is reusable only when every
        # input that can change the result still matches: GPU identity,
        # driver, Torch/CUDA, installed attention packages, and the engine
        # source hashes.  Keep the run-local copy so diagnostics retain the
        # exact receipt used by this installation.
        cached_kernel = self.root / 'kernel-capabilities.json'
        hardware_data = self.plan.get('inventory', {}).get('hardware')
        receipt = (reusable_kernel_receipt(cached_kernel, hardware_data)
                   if isinstance(hardware_data, dict) else None)
        if receipt is None:
            self.command('kernels', [python, '-m', 'freevideo_engine', 'doctor', '--probe', '--require-paths', '--out', kernel_report])
        else:
            save(kernel_report, receipt)
            self.ui.event('setup_cache', key='kernels', detail='Reused matching GPU kernel checks')

    def record_kernel_validation(self, results, kernel_report):
        sage_manifest = results['sage']
        if sage_manifest is None:
            return
        sage_record = json.loads(sage_manifest.read_text(encoding='utf-8'))
        kernels = json.loads(kernel_report.read_text(encoding='utf-8'))
        sage_record['kernel_validation'] = ('Small Sage2 kernels passed on ' + self.plan['inventory']['selected_gpu']['uuid']
            if 'sage2' in kernels['usable_attention_backends'] else 'Sage2 probe failed; see ' + str(kernel_report))
        save(sage_manifest, sage_record)

    def prepare_tools(self):
        uv_spec = self.versions['uv']
        if self.system == 'Windows':
            from .uv_bootstrap import prepare_windows
            uv = prepare_windows(self.root, uv_spec, self.network, self.env, self.fetch)
        else:
            archive = self.root / 'downloads' / 'uv.tar.gz'
            from .system import bootstrap_root
            previous = bootstrap_root(self.root) / ('uv-' + uv_spec['version'] + '.tar.gz')
            if not archive.exists() and previous.is_file() and digest(previous) == uv_spec['sha256']:
                archive.parent.mkdir(parents=True, exist_ok=True)
                try:
                    os.link(previous, archive)
                except OSError:
                    shutil.copyfile(previous, archive)
            self.fetch(uv_spec['url'], archive, uv_spec['sha256'])
            unpack_folder(archive, self.root / 'tools', 'uv-x86_64-unknown-linux-gnu')
            uv = self.root / 'tools' / 'uv-x86_64-unknown-linux-gnu' / 'uv'
        return uv

    def execute(self):
        if self.int8_check_first:
            prepare_end(self.ui)  # The GPU precheck is already execution work.
            # The installed environment runs this source's probes (PYTHONPATH);
            # the receipt is reused by the check after installation.
            self.ui.phase('Verify installation on your GPU', 0, 8)
            report = self.run_dir / 'kernel-capabilities.before.json'
            self.check_kernels(self.pythons['engine'], report)
            require_int8_kernels(self.plan, report)
            self.mark_unfinished()
        self.ui.phase('Prepare download tools', 0, 8)
        prepare_step(self.ui, 'Preparing download tools')
        uv = self.prepare_tools()
        self.env['FREEVIDEO_UV'] = str(uv)
        from .install_schedule import run
        tasks, pythons, comfy = self.component_tasks(uv)
        total = len(tasks) + 4  # Bootstrap, preparation, checks and final readiness.
        phase = 'Install with space saver' if self.plan.get('disk_mode') == 'extreme' else 'Install components in parallel'
        weighted = dict(finished=set(), fetched=0, built=0., shown=1.)
        build_bytes = INSTALL_PHASE_BUILD_BYTES if self.system != 'Windows' and 'sage' in tasks else 0
        def publish():
            with self.state_lock:
                units = install_phase_units(len(tasks), weighted['finished'], self.plan.get('model_download_bytes') or 0,
                                            weighted['fetched'], build_bytes, weighted['built'])
                # Never step back: a restarted file may report fewer bytes for a moment.
                weighted['shown'] = done = max(weighted['shown'], 1 + units)
            self.ui.phase(phase, done, total)
        def scheduling(name, status, completed, count):
            prepare_end(self.ui)  # The first real task shows from here on.
            with self.state_lock:
                self.state.setdefault('schedule', {})[name] = dict(status=status, after=tasks[name]['after'],
                    exclusive_writers=tasks[name]['writes'], epoch=time.time())
                save(self.run_dir / 'status.json', self.state)
                if status in ('complete', 'skipped'):
                    weighted['finished'].add(name)
            publish()
        def model_bytes(groups):
            weighted['fetched'] = sum(min(group.get('download_bytes') or 0, group.get('downloaded_bytes') or 0)
                                      for group in groups or ())
            publish()
        self.model_bytes_callback = model_bytes
        def built(fraction):
            if fraction <= weighted['built']:
                return  # A repeated heartbeat adds nothing to show.
            weighted['built'] = fraction
            publish()
        self.build_callback = built
        self.ui.phase(phase, 1, total)
        results = run(tasks, self.cancel, progress=scheduling,
                      workers=1 if self.plan.get('disk_mode') == 'extreme' else 3)
        python, encoder_python = self.pythons['engine'], self.pythons['encoder']
        prepared = self.run_dir / 'prepared.json'
        self.ui.phase('Optimize model storage', total - 3, total)
        self.command('prepare', [python, '-m', 'freevideo_engine.provision', '--plan', self.run_dir / 'plan.json',
                                '--prepare', '--out', prepared])
        self.ui.phase('Verify installation on your GPU', total - 2, total)
        for name, executable in pythons.items():
            self.command(name + '-dependency-check', [uv, 'pip', 'check', '--python', executable])
            self.command(name + '-freeze', [uv, 'pip', 'freeze', '--python', executable])
        kernel_report = self.run_dir / 'kernel-capabilities.json'
        self.check_kernels(python, kernel_report)
        require_int8_kernels(self.plan, kernel_report)
        self.command('storage', [python, '-m', 'freevideo_engine.provision', '--plan', self.run_dir / 'plan.json',
                                 '--cleanup', '--out', self.run_dir / 'storage.json'])
        self.record_kernel_validation(results, kernel_report)
        self.ui.phase('Finish setup', total - 1, total)
        configuration = self.machine_configuration(python, encoder_python, comfy, prepared)
        # Commit readiness only after all steps pass. Failed/rerun setup files
        # remain available, and no model/output cleanup runs automatically.
        self.monitor_stop.set()
        self.monitor_thread.join(timeout=5)
        if self.monitor_thread.is_alive() or self.cancel.is_set():
            raise RuntimeError(self.state.get('resource_guard', 'Installation monitoring did not stop cleanly.'))
        save(self.root / 'machine.json', configuration)
        self.ui.phase('Setup complete', total, total)
        return configuration


# What the rest of an installation weighs against the model download in the
# overall bar: PyTorch wheels, packages, sources and checks, as bytes.
INSTALL_PHASE_OTHER_BYTES = 6 * 2**30


# The GPU acceleration build is one task of the phase but takes minutes, so it
# weighs in the same way: as a share of the phase that advances with its counter.
# Measured on a fresh Linux install: the compile ran about twice as long as the
# 21 GiB model download, so it takes a share of the bar on that order.
INSTALL_PHASE_BUILD_BYTES = 12 * 2**30


def install_phase_units(tasks, finished, download_bytes, fetched_bytes, build_bytes=0, built=0.):
    """Units of the parallel install phase completed, out of ``tasks``.

    Counting finished tasks left the overall bar still for the whole model
    download (one task, most of the time). That task now takes a share of the
    phase in proportion to its bytes and advances with the bytes fetched. With
    ``build_bytes`` the compile task does the same, advancing with ``built``
    (the fraction of its compile steps done).
    """
    if download_bytes <= 0 and build_bytes <= 0:
        return len(finished)
    # Only a task that has its own share leaves the ordinary count; one without
    # (nothing to download, no build on this platform) counts like any other.
    weighted = ({'models'} if download_bytes > 0 else set()) | ({'sage'} if build_bytes > 0 else set())
    others = len(finished - weighted)
    count = max(1, tasks - len(weighted))
    models = 1. if 'models' in finished else min(1., max(0, fetched_bytes) / download_bytes) if download_bytes > 0 else 0.
    build = 1. if 'sage' in finished else min(1., max(0., built))
    done = (INSTALL_PHASE_OTHER_BYTES * others / count
            + max(0, download_bytes) * models + max(0, build_bytes) * build)
    return tasks * done / (INSTALL_PHASE_OTHER_BYTES + max(0, download_bytes) + max(0, build_bytes))


class Prefetcher:
    """Download the prepared model an installation is switching to, beside the one in use.

    provision --prefetch holds the setup lease (no concurrent setup run) and
    nothing else: a running request keeps the engine lease, so generation
    continues on the installed model. machine.json is unchanged and nothing
    is removed. Progress uses the installer's step reporting.
    """
    command = Installer.command

    def __init__(self, value, ui=None):
        self.plan = value
        self.root = Path(value['root'])
        self.system = value['inventory'].get('hardware', {}).get('system', platform.system())
        self.layout = value.get('environment_layout', 'unified')
        self.pythons = role_pythons(self.root, self.layout, self.system)
        self.runtime_fd = None
        self.run_dir = self.root / 'setup-runs' / (time.strftime('%Y%m%dT%H%M%SZ', time.gmtime()) + '-prefetch-' + str(os.getpid()))
        self.run_dir.mkdir(parents=True, exist_ok=False)
        save(self.run_dir / 'plan.json', value)
        env = dict(os.environ, FREEVIDEO_HOME=str(self.root), FREEVIDEO_MODEL_ROOT=value['model_dir'],
                   HF_HOME=str(self.root / 'downloads' / 'huggingface'), HF_HUB_DISABLE_TELEMETRY='1',
                   HF_HUB_OFFLINE='0', TRANSFORMERS_OFFLINE='0', PYTHONUNBUFFERED='1', PYTHONUTF8='1',
                   PYTHONIOENCODING='utf-8', PYTHONPATH=str(SOURCE),
                   FREEVIDEO_NETWORK_PLAN=str(self.run_dir / 'plan.json'),
                   FREEVIDEO_NETWORK_EVENTS=str(self.run_dir / 'network.jsonl'))
        env.pop(LOCK_ENV, None)
        self.env = network.proxy_environment(env)
        self.state = {'status': 'running', 'steps': [], 'plan': value, 'prefetch': True}
        self.state_lock = threading.Lock()
        self.cancel = threading.Event()
        self.ui = ui or TerminalUI('Model download', plain=True)

    def run(self):
        out = self.run_dir / 'prefetch.json'
        self.ui.phase('Download the faster model', 1, 2)
        self.command('models', [self.pythons['engine'], '-m', 'freevideo_engine.provision',
                                '--plan', self.run_dir / 'plan.json', '--prefetch', '--out', out])
        result = json.loads(out.read_text(encoding='utf-8'))
        self.state.update(status='complete' if result.get('complete') else 'incomplete', result=result)
        save(self.run_dir / 'status.json', self.state)
        self.ui.phase('Model downloaded' if result.get('complete') else 'Model download incomplete', 2, 2)
        return result


def run_prefetch(value, ui):
    try:
        prefetcher = Prefetcher(value, ui)
        ui.start(prefetcher.run_dir)
        result = prefetcher.run()
    except BaseException as error:
        message = str(error) if not isinstance(error, KeyboardInterrupt) else 'Stopped'
        ui.event('failure', error=message)
        print('\nModel download stopped: %s\nThe installed model is unchanged and still in use; downloaded files '
              'are kept for the next attempt.' % message, file=sys.stderr)
        return 130 if isinstance(error, KeyboardInterrupt) else 1
    finally:
        ui.close()
    if not result.get('complete'):
        print('\nSome model files are still missing; run the download again.', file=sys.stderr)
        return 1
    print('\nThe model is downloaded and verified. Run setup with the same --prepared-format to switch to it.')
    return 0


def main(argv=None):
    shown = []
    try:
        return run_main(argv, shown)
    finally:
        # An interrupt or an unexpected error anywhere must not leave the step running on the card.
        for ui in shown:
            prepare_end(ui, False)


def install_image_model(engine_root, model_root):
    """The optional image model, after the video installation is complete; its failure never fails setup."""
    from .image_gen import image_pack
    last = [-1]
    def progress(value):
        total, done = value.get('total') or 0, value.get('done') or 0
        if total and done * 100 // total != last[0]:
            last[0] = done * 100 // total
            print('Image model: %d%%' % last[0], flush=True)
    print('Downloading the image model (%.1f GiB)…' % (sum(r['bytes'] for r in image_pack.rows()) / 2**30), flush=True)
    try:
        image_pack.install(Path(model_root), progress, engine_root=Path(engine_root))
    except image_pack.PackError as error:
        print('The image model was not downloaded (%s). Download it later from the launcher.' % error.reason, file=sys.stderr)
    except (OSError, ValueError, RuntimeError) as error:
        print('The image model was not downloaded (%s). Download it later from the launcher.' % type(error).__name__, file=sys.stderr)
    else:
        print('Image model ready.')


def run_main(argv, shown):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--root', type=Path, default=Path(os.environ.get('FREEVIDEO_HOME', DEFAULT_ROOT)))
    parser.add_argument('--gpu', help='Physical nvidia-smi index or full GPU UUID')
    parser.add_argument('--environment', choices=('unified', 'dual'),
                        help='New installs default to unified; updates retain their saved layout. Existing environments are kept when switching.')
    parser.add_argument('--models', type=Path, help='Reuse/download official model files in this directory')
    parser.add_argument('--sampling-caches', action=argparse.BooleanOptionalAction, default=None,
                        help='Install every quality level in advance (default for new installations; existing ones keep '
                             'their choice). The default 8 + 3 refinement tables are always installed.')
    parser.add_argument('--image-model', action='store_true',
                        help='After setup, also download the optional image generation model (about 16 GiB). '
                             'A failure here does not fail setup; the launcher can download it later')
    parser.add_argument('--prepared-format', choices=('auto', 'int8', 'fp8'), default='auto',
                        help='auto: an installation keeps its recorded format and new installations use int8 on GeForce '
                             'and Ampere cards, FP8 elsewhere. int8/fp8 switch explicitly; files of the other format are kept')
    parser.add_argument('--prefetch-only', action='store_true',
                        help='With --prepared-format: download and verify that model beside the installed one, which stays '
                             'in use. No other setup step runs and machine.json is unchanged')
    parser.add_argument('--model-source', choices=('prepared', 'source'), default='prepared',
                        help='Default: download the tested slim model matching the GPU format. source: explicitly download original weights and convert locally')
    parser.add_argument('--encoder-models', type=Path, help='Directory containing text_encoders/')
    parser.add_argument('--reuse-models', type=Path, help='Scan an existing model library, verify content against the tested version and import matching files; only missing models are downloaded')
    parser.add_argument('--reuse-models-manifest', type=Path, help='Versioned JSON containing model library roots, including ComfyUI extra model paths')
    parser.add_argument('--copy-existing-models', action='store_true', help='Copy verified local models instead of using same-disk hardlinks; source files are kept')
    parser.add_argument('--allow-model-restart', action='store_true', help='Permit a fresh download when an incomplete model cannot resume; retains old data and may use extra download/disk space')
    cache_options = parser.add_mutually_exclusive_group()
    cache_options.add_argument('--cache', type=Path, help='Verify and reuse an existing FP8 cache')
    cache_options.add_argument('--rebuild-cache', action='store_true', help='Recreate FP8 from the tested source weights, downloading missing sources; preserve failed caches')
    parser.add_argument('--storage', choices=('compact', 'retain'), help='Default compact: stream FP8 and remove installer-owned conversion sources after verification; retain keeps sources for re-quantization')
    parser.add_argument('--frontend-root', type=Path, help=argparse.SUPPRESS)
    parser.add_argument('--frontend-separate', action='store_true', help=argparse.SUPPRESS)
    parser.add_argument('--frontend-download', action='store_true', help=argparse.SUPPRESS)
    parser.add_argument('--frontend-repair-python', type=Path, help=argparse.SUPPRESS)
    parser.add_argument('--verify', choices=('auto', 'full'), default='auto', help='auto reuses unchanged model receipts; full rereads every required tensor')
    parser.add_argument('--wheel-cache', type=Path, help='Reusable local Sage2 wheel cache, keyed by architecture and ABI')
    parser.add_argument('--rebuild-sage', action='store_true', help='Measure a fresh source build, retaining previous build artifacts')
    parser.add_argument('--vram-gib', type=float, help='Save an explicit nominal VRAM cap; default uses detected resources')
    parser.add_argument('--ram-gib', type=float, help='Save an explicit nominal RAM cap; default uses detected resources')
    resources = parser.add_mutually_exclusive_group()
    resources.add_argument('--keep-resource-limits', action='store_true', help='Reuse saved VRAM/RAM caps on update or retry; explicit capacity options override them')
    resources.add_argument('--auto-resources', action='store_true', help='Compatibility alias for the default: detect resources without reusing saved capacity caps')
    parser.add_argument('--network', choices=('auto', 'official'), default='auto', help='Auto: rank sources; official: original upstream sources only. Compare configured proxy and temporary direct routes')
    parser.add_argument('--network-timeout', type=float, default=5, help='Per-connection/probe timeout in seconds (1–30); stalled transfers retry other sources')
    parser.add_argument('--model-downloader', choices=['auto', 'xet'], default='auto',
                        help='xet: require official HF Xet for large weights; no ModelScope/HTTP fallback. Small configs use HTTP; existing files/partials retained')
    parser.add_argument('--plan', '--check', action='store_true', help='Read-only preflight with small network samples; no installation files are written')
    parser.add_argument('--download-list', action='store_true', help='Verify existing managed files while planning a third-party download list')
    parser.add_argument('--json', action='store_true', help='Print preflight as JSON')
    parser.add_argument('--plain', action='store_true', help='Disable live terminal rendering; append readable log lines')
    parser.add_argument('--verbose', action='store_true', help='Show full setup details, license links and per-step log paths')
    parser.add_argument('--no-color', action='store_true', help='Disable colors (also respects NO_COLOR)')
    parser.add_argument('--hardware-json', type=Path, help='Offline inventory fixture, only with --plan')
    parser.add_argument('--yes', action='store_true')
    parser.add_argument('--accept-model-license', action='store_true')
    parser.add_argument('--no-launch', action='store_true',
                        help='Linux: finish after the engine instead of installing ComfyUI and opening FreeVideo')
    parser.add_argument('--approved-plan', type=Path, help='GUI confirmation receipt; changed paths, models or larger disk/download requirements require a new review')
    args = parser.parse_args(argv)
    if not 1 <= args.network_timeout <= 30:
        parser.error('--network-timeout must be between 1 and 30 seconds')
    if args.hardware_json and not args.plan:
        parser.error('--hardware-json is only permitted with --plan')
    if args.json and not args.plan:
        parser.error('--json requires --plan')
    if args.auto_resources and (args.vram_gib is not None or args.ram_gib is not None):
        parser.error('--auto-resources cannot be combined with --vram-gib or --ram-gib')
    if args.copy_existing_models and not (args.reuse_models or args.reuse_models_manifest):
        parser.error('--copy-existing-models requires --reuse-models or --reuse-models-manifest')
    if args.prefetch_only and args.prepared_format == 'auto':
        parser.error('--prefetch-only needs --prepared-format int8 or fp8')
    ui = TerminalUI(platform.system() + ' setup', plain=args.plain, no_color=args.no_color,
                    verbose=args.verbose, show_location=args.verbose)
    shown.append(ui)
    try:
        from .local_models import progress_output
        if platform.system() == 'Windows' and not args.plan:
            from .curl_windows import ensure
            def curl_progress(message):
                print(json.dumps(message), flush=True)
            os.environ['FREEVIDEO_CURL'] = execution_paths.execution_path(ensure(args.root, progress=curl_progress))
        value = plan(args, local_progress=progress_output if os.environ.get('FREEVIDEO_UI_EVENTS') == '1' or not args.json else None,
                     stage=None if args.plan else lambda *step: prepare_step(ui, *step))
    except (OSError, RuntimeError, ValueError, subprocess.CalledProcessError) as error:
        prepare_end(ui, False)
        from .model_guidance import DownloadListError
        if isinstance(error, DownloadListError):
            print('Download list error: ' + error.key, file=sys.stderr)
        print('Preflight failed: ' + (error.original_error if isinstance(error, DownloadListError) else str(error)),
              file=sys.stderr)
        return 1
    print(json.dumps(value, indent=2)) if args.json else display(value, ui, verbose=args.verbose)
    if args.plan:
        return 1 if value['errors'] else 0
    if value['errors']:
        prepare_end(ui, False)
        return 1
    try:
        accepted = confirmed(args, value, ui=ui)
    except KeyboardInterrupt:
        prepare_end(ui, False)
        print('\nCancelled. No engine or model installation was started.')
        return 130
    except ValueError as error:
        prepare_end(ui, False)
        print(str(error), file=sys.stderr)
        return 1
    if not accepted:
        prepare_end(ui, False)
        print('Cancelled. No engine or model installation was started.')
        return 0
    if args.prefetch_only:
        prepare_end(ui)
        return run_prefetch(value, ui)
    try:
        installer_class = Installer
        if value.get('device_backend') == 'mps':
            from .macos_setup import Installer as installer_class
        installer = installer_class(value, ui)
    except BlockingIOError:
        prepare_end(ui, False)
        print('Setup, testing or generation is using this installation/GPU lock. Retry after it finishes.', file=sys.stderr)
        from .locking import lock_holders
        owners = lock_holders([Path(value['root']) / 'setup.lock', os.environ.get('FREEVIDEO_LOCK_PATH', str(Path(value['root']) / 'engine.lock'))])
        if owners:
            print('Processes with open lock handles: %s. Stop the old task before retrying; do not delete lock files.' % ', '.join(map(str, owners)), file=sys.stderr)
        return 1
    except (OSError, ValueError) as error:
        prepare_end(ui, False)
        print('Setup could not start: ' + str(error), file=sys.stderr)
        return 1
    def interrupted(signum, frame):
        raise KeyboardInterrupt('Setup interrupted by signal %s' % signum)
    previous = processes.termination_handler(interrupted)
    try:
        ui.start(installer.run_dir)
        installer.start_monitor()
        if value.get('device_backend') == 'mps':
            prepare_end(ui)  # The Mac installer does not schedule through execute() above.
        installer.execute()
        installer.state['status'] = 'complete'
    except BaseException as error:
        installer.state.update(status='failed', error='%s: %s' % (type(error).__name__, error))
        prepare_end(ui, False)
        ui.phase('Setup interrupted' if isinstance(error, KeyboardInterrupt) else 'Setup failed', ui.done, ui.total)
    finally:
        try:
            installer.monitor_stop.set()
            if installer.monitor_thread:
                installer.monitor_thread.join(timeout=5)
            installer.state['wall_seconds'] = time.monotonic() - installer.started
            save(installer.run_dir / 'status.json', installer.state)
        except OSError as error:
            installer.state.update(status='failed', error='Could not save final setup status: ' + repr(error))
        finally:
            processes.restore_handlers(previous)
            installer.locks.close()
            ui.close()
    if installer.state['status'] == 'complete':
        if args.verbose:
            print('Configuration: %s' % (installer.root / 'machine.json'))
        if args.image_model and platform.system() != 'Darwin':
            install_image_model(installer.root, value['model_dir'])
        from .comfy_service import after_setup, continues_after_setup
        if continues_after_setup(no_launch=args.no_launch, approved_plan=args.approved_plan):
            print('\nSetup complete.')
            return after_setup(installer.root)
        entry = '.\\test.ps1' if platform.system() == 'Windows' else './test.sh'
        print('\nSetup complete. Next: %s --root "%s"' % (entry, installer.root))
        return 0
    ui.event('failure', error=installer.state.get('resource_guard') or installer.state['error'])
    print('\nSetup failed: %s\nAll files retained. Logs: %s\nRerun the same setup command to resume.' %
          (installer.state.get('resource_guard') or installer.state['error'], installer.run_dir), file=sys.stderr)
    return 1


if __name__ == '__main__':
    raise SystemExit(main())