"""Explicit whole-disk installer. Importing this module never mutates storage.

Live payload contract: /etc/hydra/live-mode/active and remove-on-install.json
must be regular files. The manifest is a JSON array of absolute paths matching
LIVE_REMOVABLE. Store all other live-only configuration in live-mode itself;
ordinary installed configuration must already be present in the payload.
"""
from __future__ import annotations

import argparse
from dataclasses import dataclass
import getpass
import fcntl
import json
import os
from pathlib import Path, PurePosixPath
import re
import shlex
import shutil
import stat
import struct
import subprocess
import sys
import tempfile
import warnings
from typing import TextIO

DEFAULT_PAYLOAD = '/run/initramfs/live/LiveOS/squashfs.img'
LIVE_REMOVABLE = (
    '/etc/systemd/system/getty@*.service.d/90-hydra-live.conf',
    '/etc/systemd/system/serial-getty@*.service.d/90-hydra-live.conf',
    '/etc/systemd/system/greetd.service.d/90-hydra-live.conf',
    '/etc/sudoers.d/90-hydra-live',
    '/etc/greetd/live.toml',
    '/etc/NetworkManager/system-connections/90-hydra-live.nmconnection',
)
DEVICE = re.compile(r'/dev/[A-Za-z0-9_.+:/-]+\Z')
KERNEL = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.+-]*\Z')
KNOWN_TYPES = {'disk', 'part', 'loop', 'rom', 'crypt', 'lvm', 'mpath', 'dm',
               'raid0', 'raid1', 'raid4', 'raid5', 'raid6', 'raid10', 'md', 'zram'}


class InstallError(RuntimeError):
    """A failed safety check or operation; never suppress this in execution."""


@dataclass
class Request:
    disk: str
    user: str
    payload: str = DEFAULT_PAYLOAD
    execute: bool = False
    confirm_erase: str | None = None
    timezone: str = 'Europe/Moscow'
    kernel: str | None = None


class Runner:
    """Checked argv-only commands. Secret-bearing commands redact all output."""
    def run(self, argv, *, input=None, sensitive=False):
        try:
            result = subprocess.run(list(argv), input=input, text=True,
                                    stdout=subprocess.PIPE, stderr=subprocess.PIPE,
                                    shell=False, check=False)
        except OSError as exc:
            raise InstallError(f'Cannot run {argv[0]}: {exc.strerror}') from exc
        if result.returncode:
            detail = '' if sensitive else ': ' + result.stderr.strip()[:2000]
            raise InstallError(f'Command failed ({result.returncode}): {shlex.join(argv)}{detail}')
        return '' if sensitive else result.stdout


class Topology:
    def __init__(self):
        self.nodes = {}
        self.edges = {}
        self.protected = set()

    @classmethod
    def from_json(cls, raw):
        try:
            data = json.loads(raw)
        except (ValueError, TypeError) as exc:
            raise InstallError('Malformed lsblk JSON') from exc
        if not isinstance(data, dict) or not isinstance(data.get('blockdevices'), list) or not data['blockdevices']:
            raise InstallError('lsblk must return a nonempty blockdevices array')
        result = cls()
        parents = []

        def visit(node, ancestor=None, trail=()):
            if not isinstance(node, dict):
                raise InstallError('Malformed lsblk node')
            path, kind = node.get('path'), node.get('type')
            if not isinstance(path, str) or not DEVICE.fullmatch(path) or '..' in PurePosixPath(path).parts:
                raise InstallError('Invalid lsblk device path')
            if path in trail or kind not in KNOWN_TYPES:
                raise InstallError('Cyclic or unknown lsblk topology')
            mounts = node.get('mountpoints')
            size, identity = node.get('size'), node.get('maj:min')
            if not isinstance(mounts, list) or any(m is not None and not isinstance(m, str) for m in mounts):
                raise InstallError('Malformed lsblk mountpoints')
            if isinstance(size, bool) or not isinstance(size, int) or size < 0:
                raise InstallError('Invalid lsblk size')
            empty_optical = (kind == 'rom' and not any(mounts)
                             and not node.get('children') and node.get('pkname') is None
                             and ancestor is None)
            if size == 0 and not empty_optical:
                raise InstallError('Zero-size device is not an unrelated empty optical drive')
            if not isinstance(identity, str) or not re.fullmatch(r'\d+:\d+', identity):
                raise InstallError('Invalid lsblk device identity')
            if path in result.nodes and any(result.nodes[path][key] != node[key] for key in ('type', 'size', 'maj:min', 'mountpoints')):
                raise InstallError('Inconsistent duplicate lsblk node')
            result.nodes[path] = node
            result.edges.setdefault(path, set())
            if any(m for m in mounts):
                result.protected.add(path)
            pkname = node.get('pkname')
            if pkname is not None:
                if not isinstance(pkname, str) or not pkname:
                    raise InstallError('Invalid lsblk parent')
                parent = pkname if pkname.startswith('/dev/') else '/dev/' + pkname
                if not DEVICE.fullmatch(parent):
                    raise InstallError('Invalid lsblk parent path')
                parents.append((path, parent))
            if ancestor:
                parents.append((path, ancestor))
            children = node.get('children', [])
            if not isinstance(children, list):
                raise InstallError('Malformed lsblk children')
            for child in children:
                visit(child, path, trail + (path,))

        for node in data['blockdevices']:
            visit(node)
        identities = {}
        for path, node in result.nodes.items():
            identity = node['maj:min']
            if identity in identities and identities[identity] != path:
                raise InstallError('Conflicting block-device identities')
            identities[identity] = path
        directed = {path: set() for path in result.nodes}
        for child, parent in parents:
            result.link(child, parent)
            directed[child].add(parent)
        visiting, visited = set(), set()
        def check_cycle(path):
            if path in visiting:
                raise InstallError('Cyclic block-device parent references')
            if path in visited:
                return
            visiting.add(path)
            for parent in directed[path]:
                check_cycle(parent)
            visiting.remove(path)
            visited.add(path)
        for path in directed:
            check_cycle(path)
        for path, node in result.nodes.items():
            if node['size'] == 0 and result.edges[path]:
                raise InstallError('Empty optical drive has block-device dependencies')
            # An undirected child edge does not establish backing ancestry.
            # Each layer must identify its own parent, even when another
            # apparently unrelated disk is the requested installation target.
            if node['type'] not in {'disk', 'rom', 'loop', 'zram'} and not directed[path]:
                raise InstallError(f"Device has no known backing parent: {path} ({node['type']})")
        return result

    def link(self, child, parent):
        if child == parent or child not in self.nodes or parent not in self.nodes:
            raise InstallError('Unresolved or cyclic block-device parent')
        self.edges[child].add(parent)
        self.edges[parent].add(child)

    def protect(self, path):
        if path not in self.nodes:
            raise InstallError(f'Cannot resolve mounted/live source: {path}')
        if self.nodes[path]['size'] == 0:
            raise InstallError(f'Empty optical drive unexpectedly backs mounted/live storage: {path}')
        self.protected.add(path)

    def component(self, path):
        seen, pending = set(), [path]
        while pending:
            current = pending.pop()
            if current not in seen:
                seen.add(current)
                pending.extend(self.edges[current] - seen)
        return seen


class SystemProbe:
    """Read-only Linux topology probes, including loop backing files."""
    def __init__(self, runner=None):
        self.runner = runner or Runner()

    def resolve(self, path):
        return os.path.realpath(path)

    def physical_disk(self, path):
        try:
            info = os.stat(path)
            if not stat.S_ISBLK(info.st_mode):
                return False
            device = Path(f'/sys/dev/block/{os.major(info.st_rdev)}:{os.minor(info.st_rdev)}')
            if not device.exists() or (device / 'partition').exists():
                return False
            # Reject loop, device mapper, md, ram and other virtual targets.
            return '/virtual/' not in str(device.resolve()) and (device / 'device').exists()
        except OSError:
            return False

    def snapshot(self, payload):
        raw = self.runner.run(['lsblk', '--json', '--paths', '--bytes', '--output',
                               'PATH,TYPE,PKNAME,MOUNTPOINTS,SIZE,MAJ:MIN'])
        # lsblk PATH can use /dev/mapper aliases while findmnt uses /dev/dm-N.
        try:
            decoded = json.loads(raw)
            def canonicalize(node):
                if not isinstance(node, dict):
                    raise ValueError()
                if not isinstance(node.get('path'), str) or not DEVICE.fullmatch(node['path']) or '..' in PurePosixPath(node['path']).parts:
                    raise ValueError()
                node['path'] = self.resolve(node['path'])
                if isinstance(node.get('pkname'), str):
                    parent = node['pkname']
                    node['pkname'] = self.resolve(parent if parent.startswith('/dev/') else '/dev/' + parent)
                children = node.get('children', [])
                if not isinstance(children, list):
                    raise ValueError()
                for child in children:
                    canonicalize(child)
            for node in decoded['blockdevices']:
                canonicalize(node)
            topo = Topology.from_json(json.dumps(decoded))
        except (ValueError, TypeError, KeyError) as exc:
            raise InstallError('Malformed lsblk JSON') from exc
        mounts = self._mounts(self.runner.run(['findmnt', '--json', '--output',
                                             'SOURCE,TARGET,FSTYPE,MAJ:MIN,OPTIONS']))
        for mount in mounts:
            source = self._block_source(mount, topo)
            if source:
                topo.protect(source)
        # Mounted loops may hide the physical filesystem that stores their file.
        for path, node in topo.nodes.items():
            if node['type'] == 'loop' and path in topo.protected:
                identity = self._loop_backing_identity(path, node['maj:min'])
                sources = [p for p, n in topo.nodes.items() if n['maj:min'] == identity]
                if len(sources) != 1:
                    raise InstallError(f'Unknown physical backing for mounted loop: {path} ({identity})')
                source = sources[0]
                topo.protect(source)
                topo.link(path, source)
        if not Path(payload).is_file():
            raise InstallError(f'Prepared squashfs payload is not a regular file: {payload}')
        source = self._source_for_path(self.resolve(payload), topo)
        if not source:
            # tmpfs/overlay payload location cannot establish live-medium ancestry.
            raise InstallError('Cannot identify the payload backing block device; use --payload on the mounted live medium')
        topo.protect(source)
        return topo

    @staticmethod
    def _loop_backing_identity(path, expected_identity):
        # LOOP_GET_STATUS64 reports the backing inode's filesystem device,
        # independent of names which dracut switch_root may have relocated.
        # lo_rdevice is nonzero when the backing inode is itself a block device.
        try:
            descriptor = os.open(path, os.O_RDONLY | os.O_CLOEXEC)
            try:
                info = os.fstat(descriptor)
                identity = f'{os.major(info.st_rdev)}:{os.minor(info.st_rdev)}'
                if not stat.S_ISBLK(info.st_mode) or identity != expected_identity:
                    raise InstallError(f'Mounted loop device identity changed: {path}')
                status = fcntl.ioctl(descriptor, 0x4C05, bytes(232))
                if not isinstance(status, bytes) or len(status) != 232:
                    raise InstallError(f'Malformed loop status: {path}')
                filesystem_device, _, block_device = struct.unpack_from('=QQQ', status)
            finally:
                os.close(descriptor)
        except (OSError, struct.error) as exc:
            raise InstallError(f'Cannot inspect mounted loop backing identity: {path}') from exc
        device = block_device or filesystem_device
        return f'{os.major(device)}:{os.minor(device)}'

    @staticmethod
    def _mounts(raw):
        try:
            data = json.loads(raw)
            roots = data['filesystems']
            if not isinstance(roots, list) or not roots:
                raise ValueError()
            result = []

            def visit(item):
                if not isinstance(item, dict) or any(not isinstance(item.get(k), str) for k in ('source', 'target', 'fstype', 'maj:min')):
                    raise ValueError()
                result.append(item)
                children = item.get('children', [])
                if not isinstance(children, list):
                    raise ValueError()
                for child in children:
                    visit(child)
            for root in roots:
                visit(root)
            return result
        except (ValueError, TypeError, KeyError) as exc:
            raise InstallError('Malformed findmnt topology') from exc

    def _block_source(self, mount, topo):
        if mount['fstype'] in {'zfs', 'btrfs'}:
            raise InstallError('Cannot safely resolve all backing disks of mounted ' + mount['fstype'])
        source = mount['source'].split('[', 1)[0]
        identity = mount['maj:min']
        matches = [p for p, n in topo.nodes.items() if n['maj:min'] == identity]
        if source.startswith('/dev/'):
            path = self.resolve(source)
            if path in topo.nodes:
                if topo.nodes[path]['maj:min'] != identity:
                    raise InstallError('Inconsistent mounted block identity')
                topo.protect(path)
                return path
            if not matches:
                raise InstallError(f'Cannot resolve mounted/live source: {source}')
        if matches:
            topo.protect(matches[0])
            return matches[0]
        if identity.split(':', 1)[0] != '0' and mount['fstype'] not in {'zfs', 'nfs', 'nfs4', 'cifs', '9p', 'virtiofs'}:
            raise InstallError(f'Unknown mounted block source: {source}')
        return None

    def _source_for_path(self, path, topo):
        raw = self.runner.run(['findmnt', '--json', '--target', path, '--output',
                               'SOURCE,TARGET,FSTYPE,MAJ:MIN,OPTIONS'])
        mounts = self._mounts(raw)
        if len(mounts) != 1:
            raise InstallError('Ambiguous backing filesystem')
        return self._block_source(mounts[0], topo)


def validate_request(request, probe):
    if not isinstance(request.disk, str) or not DEVICE.fullmatch(request.disk) or '..' in PurePosixPath(request.disk).parts:
        raise InstallError('Choose an explicit /dev whole-disk device')
    if not re.fullmatch(r'[a-z_][a-z0-9_-]{0,31}', request.user) or request.user in {'root', 'hydra-live', 'greetd'}:
        raise InstallError('Choose a valid nonreserved lowercase Unix username')
    if not re.fullmatch(r'[A-Za-z_+-]+(?:/[A-Za-z0-9_+-]+)+', request.timezone):
        raise InstallError('Invalid timezone; use an IANA name such as Europe/Moscow')
    if not Path(request.payload).is_absolute() or any(ord(c) < 32 for c in request.payload):
        raise InstallError('Payload must be an absolute path without control characters')
    if request.kernel is not None and not KERNEL.fullmatch(request.kernel):
        raise InstallError('Invalid kernel version')
    target = probe.resolve(request.disk)
    if not DEVICE.fullmatch(target) or not probe.physical_disk(target):
        raise InstallError(f'Target is not a physical whole block disk: {target}')
    if request.execute and request.confirm_erase != target:
        raise InstallError(f'Execution requires --confirm-erase {target} exactly')
    topo = probe.snapshot(request.payload)
    if target not in topo.nodes or topo.nodes[target]['type'] != 'disk':
        raise InstallError('Target is not a known whole disk')
    if topo.nodes[target]['size'] < 4 * 1024 ** 3:
        raise InstallError('Target disk is smaller than the minimum 4 GiB')
    forbidden = topo.component(target) & topo.protected
    if forbidden:
        raise InstallError('Target backs mounted/root/live storage: ' + ', '.join(sorted(forbidden)))
    return target


def partitions(target):
    suffix = 'p' if target[-1].isdigit() else ''
    return target + suffix + '1', target + suffix + '2'


def partition_commands(target):
    esp, root = partitions(target)
    return [
        ['parted', '--script', target, 'mklabel', 'gpt'],
        ['parted', '--script', target, 'unit', 'MiB', 'mkpart', 'ESP', 'fat32', '1MiB', '1025MiB'],
        ['parted', '--script', target, 'set', '1', 'esp', 'on'],
        ['parted', '--script', target, 'unit', 'MiB', 'mkpart', 'root', 'ext4', '1025MiB', '100%'],
        ['partprobe', target], ['udevadm', 'settle'],
        ['mkfs.vfat', '-F', '32', '-n', 'HYDRA_EFI', esp],
        ['mkfs.ext4', '-F', '-L', 'HYDRA_ROOT', root],
    ]


def grub_command(root):
    return ['chroot', str(root), 'grub-install', '--target=x86_64-efi',
            '--efi-directory=/boot/efi', '--bootloader-id=HydraOS', '--removable', '--no-nvram']


def render_plan(request, target, root):
    esp, part = partitions(target)
    commands = partition_commands(target) + [
        ['mount', part, str(root)], ['unsquashfs', '-f', '-d', str(root), request.payload],
        ['mount', esp, str(Path(root) / 'boot/efi')],
        ['blkid', '-s', 'UUID', '-o', 'value', part],
        ['blkid', '-s', 'UUID', '-o', 'value', esp],
        ['mount', '--rbind', '/dev', str(Path(root) / 'dev')],
        ['mount', '--make-rslave', str(Path(root) / 'dev')],
        ['mount', '-t', 'proc', 'proc', str(Path(root) / 'proc')],
        ['mount', '--rbind', '/sys', str(Path(root) / 'sys')],
        ['mount', '--make-rslave', str(Path(root) / 'sys')],
        ['chroot', str(root), 'locale-gen'],
        ['chroot', str(root), 'useradd', '--create-home', '--groups', 'wheel,kvm,video,render,audio', '--shell', '/bin/bash', request.user],
        ['chroot', str(root), 'chpasswd'],
        ['chroot', str(root), 'passwd', '--lock', 'root'],
        ['chroot', str(root), 'systemd-machine-id-setup'],
        ['chroot', str(root), 'dracut', '--force', '--no-hostonly', '--omit', 'dmsquash-live',
         '/boot/initramfs-<kernel>.img', '<kernel>'],
        grub_command(root), ['chroot', str(root), 'grub-mkconfig', '-o', '/boot/grub/grub.cfg'],
    ]
    lines = [f'HydraOS {"EXECUTION" if request.execute else "dry-run"}: erase all data on {target}.',
             'GPT: exactly 1 GiB FAT32 ESP, remaining space ext4 root.',
             f'Prepared payload: {request.payload}; account: {request.user}; timezone: {request.timezone}.',
             'Commands (UUIDs/kernel discovered after unpacking; no commands run in dry-run):']
    lines.extend('  ' + shlex.join(c) for c in commands)
    lines.extend(['Write UUID fstab, en_US.UTF-8 and ru_RU.UTF-8, timezone, installed dracut/GRUB defaults.',
                  'Remove allowlisted live-mode files, hydra-live account and /home/hydra-live; reset machine-id.',
                  'Ensure wheel,kvm,video,render,audio groups exist before creating the installed account.',
                  'chpasswd receives the TTY-entered password on private stdin; root remains locked.',
                  'Unmount tracked sys/proc/dev/ESP/root in reverse order on success or failure.',
                  f'To execute, add --execute --confirm-erase {target} (as root; no automatic sudo).'])
    return '\n'.join(lines)


def target_path(root, relative, *, symlinks=False):
    """Resolve a path inside a target, interpreting absolute symlinks as chroot paths."""
    root = Path(root).resolve()
    parts = list(PurePosixPath(relative).parts)
    if parts and parts[0] == '/':
        parts.pop(0)
    resolved, hops = [], 0
    while parts:
        part = parts.pop(0)
        if part in ('', '.'):
            continue
        if part == '..':
            if not resolved:
                raise InstallError('Target path escapes root')
            resolved.pop()
            continue
        candidate = root.joinpath(*resolved, part)
        if candidate.is_symlink():
            if not symlinks:
                raise InstallError(f'Refusing symlink traversal in target: {relative}')
            hops += 1
            if hops > 40:
                raise InstallError('Target symlink cycle')
            link = PurePosixPath(os.readlink(candidate))
            extra = list(link.parts)
            if link.is_absolute():
                resolved = []
                extra.pop(0)
            parts = extra + parts
        else:
            resolved.append(part)
    return root.joinpath(*resolved)


def remove_live_files(root):
    directory = target_path(root, 'etc/hydra/live-mode')
    if not directory.is_dir():
        raise InstallError('Payload missing /etc/hydra/live-mode contract')
    manifest = target_path(root, 'etc/hydra/live-mode/remove-on-install.json')
    marker = target_path(root, 'etc/hydra/live-mode/active')
    if not manifest.is_file() or not marker.is_file():
        raise InstallError('Payload live-mode marker/manifest missing')
    try:
        paths = json.loads(manifest.read_text())
    except (OSError, ValueError) as exc:
        raise InstallError('Invalid live-mode removal manifest') from exc
    if not isinstance(paths, list):
        raise InstallError('Live removal manifest must be a JSON array')
    removals = []
    for path in paths:
        if not isinstance(path, str) or not path.startswith('/') or '..' in PurePosixPath(path).parts or str(PurePosixPath(path)) != path:
            raise InstallError('Invalid path in live removal manifest')
        if not any(re.fullmatch(re.escape(pattern).replace(r'\*', r'[A-Za-z0-9_.-]+'), path) for pattern in LIVE_REMOVABLE):
            raise InstallError(f'Live manifest path is not allowlisted: {path}')
        leaf = PurePosixPath(path)
        parent = target_path(root, str(leaf.parent))
        candidate = parent / leaf.name
        if candidate.exists() and not candidate.is_file() and not candidate.is_symlink():
            raise InstallError('Live manifest may only remove files/symlinks')
        removals.append(candidate)
    for path in removals:
        path.unlink(missing_ok=True)
    # shutil.rmtree never follows directory symlinks inside this directory.
    shutil.rmtree(directory)


def remove_live_account(root, run):
    """Remove the payload's fixed local live identity, before binding live /proc."""
    passwd = target_path(root, 'etc/passwd')
    try:
        rows = [row.split(':') for row in passwd.read_text().splitlines() if row.split(':', 1)[0] == 'hydra-live']
    except OSError as exc:
        raise InstallError('Payload missing readable /etc/passwd') from exc
    if len(rows) > 1:
        raise InstallError('Duplicate live account in payload')
    if rows:
        row = rows[0]
        if len(row) != 7 or not row[2].isdigit() or int(row[2]) < 1000 or row[5] != '/home/hydra-live':
            raise InstallError('Live account must have a nonroot UID and exactly /home/hydra-live')
    home = target_path(root, 'home/hydra-live')
    if home.exists() and not home.is_dir():
        raise InstallError('Live home must be an ordinary directory')
    if rows:
        # /proc is not mounted yet, so the live session's identical UID cannot
        # make userdel mistake a running live process for a target process.
        run(['chroot', str(root), 'userdel', 'hydra-live'])
    if home.exists():
        shutil.rmtree(home)
    for spool in ('var/mail/hydra-live', 'var/spool/mail/hydra-live'):
        parent = target_path(root, str(PurePosixPath(spool).parent), symlinks=True)
        leaf = parent / 'hydra-live'
        if leaf.is_file() or leaf.is_symlink():
            leaf.unlink()


def select_kernel(root, requested):
    modules = target_path(root, '/lib/modules', symlinks=True)
    if not modules.is_dir():
        raise InstallError('Payload has no installed kernel modules')
    versions = sorted(p.name for p in modules.iterdir() if not p.is_symlink() and p.is_dir() and KERNEL.fullmatch(p.name))
    if requested:
        if requested not in versions:
            raise InstallError(f'Requested kernel not installed: {requested}')
        version = requested
    elif len(versions) == 1:
        version = versions[0]
    else:
        raise InstallError('Select --kernel explicitly when payload has zero or multiple kernels: ' + ', '.join(versions))
    if not target_path(root, '/boot/vmlinuz-' + version, symlinks=True).is_file():
        raise InstallError(f'Payload missing /boot/vmlinuz-{version}')
    return version


def write_config(root, relative, value, mode=0o644):
    path = target_path(root, relative)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(value)
    path.chmod(mode)


def install(request, runner, probe, root, password, log: TextIO):
    """Execute into an empty mount directory; inject a runner for disk-free tests."""
    if not request.execute:
        raise InstallError('Installation requires --execute')
    if not isinstance(password, str) or not password or any(c in password for c in '\r\n\x00'):
        raise InstallError('Password must be nonempty and contain no newline or NUL')
    target = validate_request(request, probe)
    root = Path(root)
    if not root.is_absolute() or root.is_symlink() or not root.is_dir() or any(root.iterdir()):
        raise InstallError('Target mount directory must be an empty absolute directory')
    mounted = []
    error = None
    journal = []

    def emit(message):
        journal.append(message)
        print(message, file=log, flush=True)

    def run(argv, **kw):
        emit('+ ' + shlex.join(argv))
        return runner.run(argv, **kw)

    def mount(argv, path, recursive=False):
        run(argv)
        mounted.append((str(path), recursive))

    try:
        run(['unsquashfs', '-s', request.payload])
        # Recheck after preflight, directly before the first destructive command.
        if validate_request(request, probe) != target:
            raise InstallError('Target device changed during validation')
        for argv in partition_commands(target):
            run(argv)
        esp, part = partitions(target)
        mount(['mount', part, str(root)], root)
        run(['unsquashfs', '-f', '-d', str(root), request.payload])
        kernel = select_kernel(root, request.kernel)
        remove_live_files(root)
        remove_live_account(root, run)
        if not target_path(root, '/usr/share/zoneinfo/' + request.timezone, symlinks=True).is_file():
            raise InstallError('Timezone does not exist in payload: ' + request.timezone)
        for folder in ('boot/efi', 'dev', 'proc', 'sys'):
            target_path(root, folder).mkdir(parents=True, exist_ok=True)
        mount(['mount', esp, str(root / 'boot/efi')], root / 'boot/efi')
        root_uuid = run(['blkid', '-s', 'UUID', '-o', 'value', part]).strip()
        esp_uuid = run(['blkid', '-s', 'UUID', '-o', 'value', esp]).strip()
        if any(not re.fullmatch(r'[A-Fa-f0-9-]+', value) for value in (root_uuid, esp_uuid)):
            raise InstallError('Missing or invalid partition UUID')
        write_config(root, 'etc/fstab', f'UUID={root_uuid} / ext4 defaults 0 1\nUUID={esp_uuid} /boot/efi vfat umask=0077 0 2\n')
        write_config(root, 'etc/locale.gen', 'en_US.UTF-8 UTF-8\nru_RU.UTF-8 UTF-8\n')
        write_config(root, 'etc/locale.conf', 'LANG=en_US.UTF-8\n')
        write_config(root, 'etc/timezone', request.timezone + '\n')
        localtime = target_path(root, 'etc/localtime', symlinks=True)
        # Replace even an absolute /etc/localtime symlink without touching the host.
        localtime_link = target_path(root, 'etc') / 'localtime'
        if localtime_link.is_symlink():
            localtime_link.unlink()
        elif localtime.exists():
            localtime.unlink()
        (root / 'etc/localtime').symlink_to('/usr/share/zoneinfo/' + request.timezone)
        write_config(root, 'etc/machine-id', '')
        dbus_machine_id = target_path(root, 'var/lib/dbus') / 'machine-id'
        dbus_machine_id.unlink(missing_ok=True)
        write_config(root, 'etc/dracut.conf.d/90-hydra-installed.conf',
                     'hostonly="no"\nhostonly_cmdline="no"\nomit_dracutmodules+=" dmsquash-live "\n# No root=live: or rd.live arguments on the installed disk.\n')
        write_config(root, 'etc/default/grub', 'GRUB_DISTRIBUTOR="HydraOS"\nGRUB_CMDLINE_LINUX=""\nGRUB_TIMEOUT=3\n')
        write_config(root, 'etc/sudoers.d/90-hydra-admin', '%wheel ALL=(ALL:ALL) ALL\n', 0o440)
        mount(['mount', '--rbind', '/dev', str(root / 'dev')], root / 'dev', True)
        run(['mount', '--make-rslave', str(root / 'dev')])
        mount(['mount', '-t', 'proc', 'proc', str(root / 'proc')], root / 'proc')
        mount(['mount', '--rbind', '/sys', str(root / 'sys')], root / 'sys', True)
        run(['mount', '--make-rslave', str(root / 'sys')])
        def chroot(*args, **kw):
            return run(['chroot', str(root), *args], **kw)
        chroot('locale-gen')
        for group in ('wheel', 'kvm', 'video', 'render', 'audio'):
            chroot('groupadd', '--force', '--system', group)
        chroot('useradd', '--create-home', '--groups', 'wheel,kvm,video,render,audio', '--shell', '/bin/bash', request.user)
        chroot('chpasswd', input=f'{request.user}:{password}\n', sensitive=True)
        password = None
        chroot('passwd', '--lock', 'root')
        chroot('systemd-machine-id-setup')
        chroot('dracut', '--force', '--no-hostonly', '--omit', 'dmsquash-live',
               '/boot/initramfs-' + kernel + '.img', kernel)
        run(grub_command(root))
        chroot('grub-mkconfig', '-o', '/boot/grub/grub.cfg')
        run(['sync'])
    except (InstallError, OSError, KeyboardInterrupt) as exc:
        error = exc
        emit(f'Installation stopped: {exc}. Target data retained for diagnosis.')
    finally:
        password = None
        if any(path == str(root) for path, _ in mounted):
            try:
                write_config(root, 'var/log/hydra-install.log', '\n'.join(journal) + '\n', 0o600)
            except (InstallError, OSError) as exc:
                emit(f'Unable to retain diagnostic in target: {exc}')
        cleanup_errors = []
        for path, recursive in reversed(mounted):
            try:
                run(['umount', *(['--recursive'] if recursive else []), path])
            except (InstallError, OSError) as exc:
                cleanup_errors.append(str(exc))
                emit(f'cleanup failed: {exc}')
        if cleanup_errors and error is None:
            error = InstallError('Mount cleanup failed: ' + '; '.join(cleanup_errors))
    if error:
        raise InstallError(str(error)) from error
    print('Installation finished; remove the live ISO before booting the installed disk.', file=log, flush=True)


def preflight(request, runner):
    if any(Path(marker).exists() for marker in ('/.dockerenv', '/run/.containerenv', '/run/systemd/container')):
        raise InstallError('Refusing disk installation in a container; boot the live ISO in a disposable VM')
    if os.geteuid() != 0:
        raise InstallError('Execution requires root inside the live environment; no automatic sudo')
    if not sys.stdin.isatty():
        raise InstallError('Execution requires a TTY for password entry')
    if not Path('/sys/firmware/efi').is_dir():
        raise InstallError('Boot the live medium in UEFI mode before installation')
    for command in ('lsblk', 'findmnt', 'parted', 'partprobe', 'udevadm', 'mkfs.vfat',
                    'mkfs.ext4', 'mount', 'umount', 'unsquashfs', 'blkid', 'chroot', 'sync'):
        if shutil.which(command) is None:
            raise InstallError('Required live installer tool missing: ' + command)
    runner.run(['unsquashfs', '-s', request.payload])


def prompt_password():
    try:
        # Only the prompt output stream is needed here; getpass opens its own
        # raw controlling-TTY input. Buffered r+ requires seekability.
        with open('/dev/tty', 'w') as tty:
            if not tty.isatty():
                raise InstallError('Password entry requires a controlling TTY')
            with warnings.catch_warnings():
                warnings.simplefilter('error', getpass.GetPassWarning)
                password = getpass.getpass('Installed account password: ', stream=tty)
                if password != getpass.getpass('Repeat password: ', stream=tty):
                    raise InstallError('Passwords differ')
            return password
    except (OSError, getpass.GetPassWarning) as exc:
        raise InstallError('Cannot securely read password from the controlling TTY') from exc


def main(argv=None):
    parser = argparse.ArgumentParser(description='HydraOS explicit whole-disk installer; dry-run by default')
    parser.add_argument('--disk', help='explicit physical whole-disk target; never automatically selected')
    parser.add_argument('--user', help='installed administrator username')
    parser.add_argument('--payload', default=DEFAULT_PAYLOAD, help='prepared live squashfs root payload')
    parser.add_argument('--execute', action='store_true')
    parser.add_argument('--confirm-erase', help='must exactly match the resolved /dev target with --execute')
    parser.add_argument('--timezone', default='Europe/Moscow')
    parser.add_argument('--kernel', help='required if payload contains multiple kernel module versions')
    args = parser.parse_args(argv)
    runner = Runner()
    try:
        if not args.disk:
            if args.execute or args.confirm_erase:
                raise InstallError('--execute requires an explicit --disk and --user')
            topo = Topology.from_json(runner.run(['lsblk', '--json', '--paths', '--bytes', '--output',
                                                'PATH,TYPE,PKNAME,MOUNTPOINTS,SIZE,MAJ:MIN']))
            print('Disks (no target selected; mounted disks are ineligible):')
            for path, node in sorted(topo.nodes.items()):
                if node['type'] == 'disk':
                    state = 'in use' if topo.component(path) & topo.protected else 'unmounted; requires full guard check'
                    print(f'  {path}  {node["size"] / 1024**3:.1f} GiB  {state}')
            print('Choose --disk DEVICE --user USER to inspect the dry-run plan.')
            return 0
        if not args.user:
            raise InstallError('--user is required with --disk')
        request = Request(**vars(args))
        probe = SystemProbe(runner)
        target = validate_request(request, probe)
        print(render_plan(request, target, '/mnt/hydra-target'))
        if not request.execute:
            return 0
        preflight(request, runner)
        password = prompt_password()
        state = Path(tempfile.mkdtemp(prefix='hydra-install-', dir='/run'))
        state.chmod(0o700)
        root = state / 'target'
        root.mkdir()
        logfile = state / 'installer.log'
        print(f'Diagnostic log: {logfile}')
        with logfile.open('w') as log:
            log.write(render_plan(request, target, str(root)) + '\n')
            install(request, runner, probe, root, password, log)
        password = None
        print(f'Installation completed. Diagnostic log: {logfile}')
        return 0
    except (InstallError, OSError, KeyboardInterrupt) as exc:
        print(f'hydra-install: {exc}', file=sys.stderr)
        return 1


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