amv-diffusion 2.1.0__py3-none-any.whl

termux_diffusion/platform.py

@@ -0,0 +1,533 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""Platform inspection, Samsung Galaxy hardware detection, memory checks, and Android OS bridges."""
+
+import ctypes
+import glob
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import urllib.parse
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger("termux_diffusion.platform")
+
+# Android Termux standard paths
+TERMUX_PREFIX = os.environ.get("PREFIX") or "/data/data/com.termux/files/usr"
+TERMUX_HOME = os.environ.get("HOME") or "/data/data/com.termux/files/home"
+
+
+def get_clean_execution_env(
+    base_env: Optional[Dict[str, str]] = None,
+    backend: str = "cpu",
+) -> Dict[str, str]:
+    """Construct clean execution environment for Termux binaries with proper library search paths.
+
+    Guarantees $PREFIX, $PREFIX/lib, and companion directories are correctly populated
+    while preventing Android system library collision (/system/, /vendor/, etc.).
+
+    Zero-Collision Rule:
+    For native Bionic Vulkan binaries (backend in ('vulkan', 'gpu')), Termux $PREFIX/lib is
+    strictly excluded from LD_LIBRARY_PATH to eliminate symbol collisions with Android Bionic
+    system libraries (/system/lib64/libunwindstack.so, etc.).
+    """
+    env = (base_env or os.environ).copy()
+    prefix = os.environ.get("PREFIX") or "/data/data/com.termux/files/usr"
+
+    if "PREFIX" not in env or not env["PREFIX"]:
+        env["PREFIX"] = prefix
+
+    bin_dir = str(Path(prefix) / "bin")
+    cur_path = env.get("PATH", "")
+    if bin_dir not in cur_path.split(":"):
+        env["PATH"] = f"{bin_dir}:{cur_path}" if cur_path else bin_dir
+
+    req_backend = str(backend or "cpu").strip().lower()
+    is_vulkan_route = req_backend in ("vulkan", "gpu")
+    is_opencl_route = req_backend in ("opencl", "cl")
+
+    forbidden_prefixes = ("/system/", "/vendor/", "/apex/", "/system_ext/", "/odm/", "/product/")
+    cur_ld = env.get("LD_LIBRARY_PATH", "")
+    existing_parts = [p for p in cur_ld.split(":") if p and not any(p.startswith(fp) for fp in forbidden_prefixes)]
+
+    if is_vulkan_route:
+        # Strictly isolate Vulkan binaries from Termux /usr/lib to prevent libc++ ABI crash
+        lib_candidates = [
+            str(Path.home() / ".local" / "share" / "ameva" / "current" / "diffusion"),
+            str(Path.home() / ".cache" / "termux-diffusion" / "lib"),
+        ]
+        # Filter out prefix/lib from existing parts for Vulkan
+        existing_parts = [p for p in existing_parts if not p.startswith(str(Path(prefix) / "lib"))]
+    elif is_opencl_route:
+        # Strictly prioritize OpenCL standalone bin directory and exclude /usr/lib (stub libOpenCL.so)
+        lib_candidates = [
+            str(Path.home() / "sd-opencl-build" / "build" / "bin"),
+            str(Path.home() / ".cache" / "termux-diffusion" / "lib"),
+        ]
+        existing_parts = [p for p in existing_parts if not p.startswith(str(Path(prefix) / "lib"))]
+    else:
+        lib_candidates = [
+            str(Path(prefix) / "lib"),
+            str(Path.home() / ".cache" / "termux-diffusion" / "lib"),
+            str(Path.home() / ".cache" / "termux-diffusion" / "staging" / "lib"),
+            str(Path.home() / ".local" / "lib"),
+        ]
+
+    merged: List[str] = []
+    for d in lib_candidates + existing_parts:
+        if d not in merged and Path(d).is_dir() and not any(d.startswith(fp) for fp in forbidden_prefixes):
+            merged.append(d)
+
+    if merged:
+        env["LD_LIBRARY_PATH"] = ":".join(merged)
+    elif is_vulkan_route and "LD_LIBRARY_PATH" in env:
+        env.pop("LD_LIBRARY_PATH", None)
+
+    # Detect libegl_shim.so for Android Mali/Samsung GOS Vulkan HAL compatibility (Vulkan only)
+    if is_vulkan_route:
+        shim_candidates = [
+            Path(prefix) / "lib" / "libegl_shim.so",
+            Path.home() / ".cache" / "termux-diffusion" / "lib" / "libegl_shim.so",
+            Path.home() / ".local" / "lib" / "libegl_shim.so",
+            Path("/data/data/com.termux/files/usr/lib/libegl_shim.so"),
+        ]
+        cur_preload = env.get("LD_PRELOAD", "")
+        for shim in shim_candidates:
+            if shim.is_file():
+                shim_str = str(shim.resolve())
+                if shim_str not in cur_preload:
+                    env["LD_PRELOAD"] = f"{shim_str}:{cur_preload}" if cur_preload else shim_str
+                break
+    elif is_opencl_route:
+        # Strip Mali Vulkan shim from LD_PRELOAD on OpenCL to prevent Adreno linker faults
+        cur_preload = env.get("LD_PRELOAD", "")
+        clean_preloads = [p for p in cur_preload.split(":") if p and "libegl_shim.so" not in p]
+        if clean_preloads:
+            env["LD_PRELOAD"] = ":".join(clean_preloads)
+        else:
+            env.pop("LD_PRELOAD", None)
+
+    return env
+
+
+# [B방안] Platform SSOT: ameva-runtime.platform 에서 공유 구현을 가져옵니다.
+try:
+    from ameva_runtime.vulkan.platform import is_termux as _ameva_is_termux
+    _AMEVA_PLATFORM_AVAILABLE = True
+except ImportError:
+    _AMEVA_PLATFORM_AVAILABLE = False
+
+
+def is_android_termux() -> bool:
+    """Check whether the current runtime environment is native Android Termux.
+
+    [B방안] ameva-runtime.platform.is_termux() 를 SSOT 로 사용하며,
+    미설치 환경에서는 인라인 구현으로 안전하게 폴백합니다.
+    """
+    if _AMEVA_PLATFORM_AVAILABLE:
+        return _ameva_is_termux()
+    if os.environ.get("TERMUX_VERSION") or os.environ.get("TERMUX_APP_PID"):
+        return True
+    if os.path.exists("/data/data/com.termux"):
+        return True
+    return False
+
+
+def is_arm64() -> bool:
+    """Check whether the host CPU architecture is 64-bit ARM (aarch64 / arm64)."""
+    machine = platform.machine().lower()
+    return machine in ("aarch64", "arm64", "armv8l", "armv8b")
+
+
+def get_default_cache_dir() -> Path:
+    """Return root cache directory for termux-diffusion."""
+    env_cache = os.environ.get("TERMUX_DIFFUSION_CACHE")
+    if env_cache:
+        return Path(env_cache).resolve()
+    return Path.home() / ".cache" / "termux-diffusion"
+
+
+def get_galaxy_gallery_dir() -> Path:
+    """Return the designated Samsung Galaxy / Android photo gallery save directory.
+    
+    Default hierarchy:
+    1. Custom environment variable (TERMUX_DIFFUSION_OUTPUT_DIR or AMEVA_OUTPUT_DIR)
+    2. Primary Android internal storage DCIM album (~/storage/dcim/TermuxDiffusion or /sdcard/DCIM/TermuxDiffusion)
+    3. Secondary Android Pictures album (~/storage/pictures/TermuxDiffusion or /sdcard/Pictures/TermuxDiffusion)
+    4. Fallback to app-private cache (~/.cache/termux-diffusion/outputs)
+    """
+    custom_dir = os.environ.get("TERMUX_DIFFUSION_OUTPUT_DIR") or os.environ.get("AMEVA_OUTPUT_DIR")
+    if custom_dir:
+        p = Path(custom_dir).expanduser().resolve()
+        try:
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+        except Exception as _e:
+            logger.debug("[platform] custom output dir failed: %s", _e)
+
+    # 1. Primary: Samsung Galaxy Internal Storage DCIM/TermuxDiffusion
+    termux_dcim = Path.home() / "storage" / "dcim" / "TermuxDiffusion"
+    if (Path.home() / "storage" / "dcim").is_dir():
+        try:
+            termux_dcim.mkdir(parents=True, exist_ok=True)
+            return termux_dcim
+        except (PermissionError, OSError) as _perm_err:
+            logger.debug("[platform] termux_dcim mkdir failed: %s", _perm_err)
+
+    sdcard_dcim = Path("/sdcard/DCIM/TermuxDiffusion")
+    if Path("/sdcard/DCIM").is_dir():
+        try:
+            sdcard_dcim.mkdir(parents=True, exist_ok=True)
+            return sdcard_dcim
+        except (PermissionError, OSError) as _perm_err:
+            logger.debug("[platform] sdcard_dcim mkdir failed: %s", _perm_err)
+
+    # 2. Secondary: Pictures/TermuxDiffusion
+    termux_storage = Path.home() / "storage" / "pictures" / "TermuxDiffusion"
+    if (Path.home() / "storage" / "pictures").is_dir():
+        try:
+            termux_storage.mkdir(parents=True, exist_ok=True)
+            return termux_storage
+        except (PermissionError, OSError) as _perm_err:
+            logger.debug("[platform] termux_storage mkdir failed: %s", _perm_err)
+
+    sdcard_pictures = Path("/sdcard/Pictures/TermuxDiffusion")
+    if Path("/sdcard/Pictures").is_dir():
+        try:
+            sdcard_pictures.mkdir(parents=True, exist_ok=True)
+            return sdcard_pictures
+        except (PermissionError, OSError) as _perm_err:
+            logger.debug("[platform] sdcard mkdir failed: %s", _perm_err)
+
+    fallback = get_default_cache_dir() / "outputs"
+    fallback.mkdir(parents=True, exist_ok=True)
+    return fallback
+
+
+
+
+
+
+def export_to_android_gallery(image_path: Path) -> Optional[Path]:
+    """Copy generated image to Samsung Gallery and broadcast media scanner intent.
+    
+    Returns:
+        Optional[Path]: Destination path in gallery if successful, None if storage permission denied.
+    """
+    try:
+        gallery_dir = get_galaxy_gallery_dir()
+        fallback_dir = get_default_cache_dir() / "outputs"
+        
+        # If gallery dir is fallback (app-private sandbox), notify user if permission is missing
+        if gallery_dir == fallback_dir and is_android_termux() and not (Path.home() / "storage").exists():
+            logger.warning(
+                "Android storage permission not granted. Image saved to app cache: %s. "
+                "To export to Samsung Gallery automatically, run 'termux-setup-storage'.",
+                image_path
+            )
+            _broadcast_media_scanner(image_path)
+            return image_path
+
+        dest = gallery_dir / image_path.name
+        if dest.resolve() != image_path.resolve():
+            shutil.copy2(image_path, dest)
+
+        _broadcast_media_scanner(dest)
+        return dest
+    except (PermissionError, OSError) as exc:
+        logger.warning(
+            "Could not export image to Android Gallery due to permission restrictions (%s). "
+            "Image is safely preserved at local path: %s. "
+            "Please run 'termux-setup-storage' to grant external gallery access.",
+            exc, image_path
+        )
+        return None
+
+
+def _broadcast_media_scanner(image_path: Path) -> None:
+    """Broadcast android.intent.action.MEDIA_SCANNER_SCAN_FILE so Galaxy Gallery indexes the file."""
+    if not is_android_termux():
+        return
+
+    am_binary = shutil.which("am") or shutil.which("termux-am")
+    if not am_binary:
+        return
+
+    file_uri = f"file://{urllib.parse.quote(str(image_path.resolve()))}"
+    try:
+        subprocess.run(
+            [am_binary, "broadcast", "-a", "android.intent.action.MEDIA_SCANNER_SCAN_FILE", "-d", file_uri],
+            capture_output=True,
+            timeout=3.0,
+            check=False
+        )
+    except Exception as exc:
+        logger.debug("Media scanner broadcast note: %s", exc)
+
+
+def get_optimal_thread_count() -> int:
+    """Calculate the optimal number of inference threads for mobile and host CPUs.
+    
+    In big.LITTLE mobile architectures (e.g., 4 Performance + 4 Efficiency cores),
+    running on all cores causes severe thermal throttling and cache thrashing.
+    We inspect sysfs CPU frequency scaling topologies when available, or dynamically
+    derive cluster sizes.
+    """
+    # 1. Try parsing Linux/Android sysfs cpufreq topology
+    try:
+        freq_files = sorted(glob.glob("/sys/devices/system/cpu/cpu[0-9]*/cpufreq/cpuinfo_max_freq"))
+        if not freq_files:
+            freq_files = sorted(glob.glob("/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_max_freq"))
+
+        if freq_files:
+            freqs: List[int] = []
+            for ff in freq_files:
+                try:
+                    with open(ff, "r", encoding="utf-8") as f:
+                        val = f.read().strip()
+                        if val.isdigit():
+                            freqs.append(int(val))
+                except (OSError, IOError) as err:
+                    logger.debug("Sysfs freq read note on '%s': %s", ff, err)
+
+            if freqs:
+                max_f = max(freqs)
+                # Count cores operating within 85% of peak frequency (Big / Mid cluster)
+                threshold = int(max_f * 0.85)
+                perf_cores = sum(1 for f in freqs if f >= threshold)
+                if perf_cores > 0:
+                    return perf_cores
+    except Exception as e:
+        logger.debug("Sysfs CPU frequency probing error: %s", e)
+
+    # 2. General fallback based on logical CPU core topology
+    total_cores = os.cpu_count() or 4
+    if is_arm64():
+        # Typical ARM mobile: 8 cores = 4 Big + 4 Little (or 1+3+4)
+        if total_cores >= 8:
+            return 4
+        elif total_cores >= 6:
+            return 4
+        elif total_cores >= 4:
+            return 4
+        return max(1, total_cores)
+    else:
+        # Desktop x86_64: Use physical cores heuristic (half of hyperthreaded cores or up to 8)
+        return max(1, min(8, total_cores // 2 if total_cores > 4 else total_cores))
+
+# Standard Unified Interface Alias
+get_optimal_threads = get_optimal_thread_count
+
+
+def _get_windows_memory_info() -> Optional[Dict[str, int]]:
+    """Retrieve accurate Windows physical RAM and commit limit via GlobalMemoryStatusEx."""
+    try:
+        class MEMORYSTATUSEX(ctypes.Structure):
+            _fields_ = [
+                ("dwLength", ctypes.c_ulong),
+                ("dwMemoryLoad", ctypes.c_ulong),
+                ("ullTotalPhys", ctypes.c_ulonglong),
+                ("ullAvailPhys", ctypes.c_ulonglong),
+                ("ullTotalPageFile", ctypes.c_ulonglong),
+                ("ullAvailPageFile", ctypes.c_ulonglong),
+                ("ullTotalVirtual", ctypes.c_ulonglong),
+                ("ullAvailVirtual", ctypes.c_ulonglong),
+                ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+            ]
+
+        stat = MEMORYSTATUSEX()
+        stat.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
+        if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)):
+            mem_total_mb = int(stat.ullTotalPhys // (1024 * 1024))
+            mem_available_mb = int(stat.ullAvailPhys // (1024 * 1024))
+            pagefile_total_mb = int(stat.ullTotalPageFile // (1024 * 1024))
+            pagefile_avail_mb = int(stat.ullAvailPageFile // (1024 * 1024))
+            
+            swap_total_mb = max(0, pagefile_total_mb - mem_total_mb)
+            swap_free_mb = max(0, pagefile_avail_mb - mem_available_mb)
+
+            return {
+                "mem_total_mb": mem_total_mb,
+                "mem_available_mb": mem_available_mb,
+                "swap_total_mb": swap_total_mb,
+                "swap_free_mb": swap_free_mb,
+                "effective_total_mb": mem_total_mb + swap_total_mb,
+                "effective_available_mb": mem_available_mb + swap_free_mb,
+            }
+    except Exception as e:
+        logger.debug("Windows GlobalMemoryStatusEx query failed: %s", e)
+    return None
+
+
+def get_memory_info() -> Dict[str, int]:
+    """Inspect system memory metrics (RAM and swap/zRAM) in MB from genuine OS interfaces."""
+    metrics = {
+        "mem_total_mb": 0,
+        "mem_available_mb": 0,
+        "swap_total_mb": 0,
+        "swap_free_mb": 0,
+        "effective_total_mb": 0,
+        "effective_available_mb": 0,
+    }
+
+    # 1. Linux & Android /proc/meminfo (Standard on Termux)
+    if os.path.exists("/proc/meminfo"):
+        try:
+            with open("/proc/meminfo", "r", encoding="utf-8") as f:
+                for line in f:
+                    parts = line.split(":")
+                    if len(parts) == 2:
+                        key = parts[0].strip()
+                        val_str = parts[1].strip().split()[0]
+                        if val_str.isdigit():
+                            val_kb = int(val_str)
+                            val_mb = val_kb // 1024
+                            if key == "MemTotal":
+                                metrics["mem_total_mb"] = val_mb
+                            elif key == "MemAvailable":
+                                metrics["mem_available_mb"] = val_mb
+                            elif key == "SwapTotal":
+                                metrics["swap_total_mb"] = val_mb
+                            elif key == "SwapFree":
+                                metrics["swap_free_mb"] = val_mb
+            metrics["effective_total_mb"] = metrics["mem_total_mb"] + metrics["swap_total_mb"]
+            metrics["effective_available_mb"] = metrics["mem_available_mb"] + metrics["swap_free_mb"]
+            return metrics
+        except Exception as e:
+            logger.debug("Failed reading /proc/meminfo: %s", e)
+
+    # 2. Windows Native Win32 API
+    if sys.platform == "win32":
+        win_mem = _get_windows_memory_info()
+        if win_mem:
+            return win_mem
+
+    # 3. Optional psutil fallback if installed
+    try:
+        import psutil  # type: ignore
+        vmem = psutil.virtual_memory()
+        smem = psutil.swap_memory()
+        metrics["mem_total_mb"] = int(vmem.total // (1024 * 1024))
+        metrics["mem_available_mb"] = int(vmem.available // (1024 * 1024))
+        metrics["swap_total_mb"] = int(smem.total // (1024 * 1024))
+        metrics["swap_free_mb"] = int(smem.free // (1024 * 1024))
+        metrics["effective_total_mb"] = metrics["mem_total_mb"] + metrics["swap_total_mb"]
+        metrics["effective_available_mb"] = metrics["mem_available_mb"] + metrics["swap_free_mb"]
+        return metrics
+    except ImportError as _psutil_err:
+        logger.debug("Optional dependency psutil not available for memory info: %s", _psutil_err)
+
+
+    return metrics
+
+
+def check_memory_safety(required_mb: int = 1500) -> Tuple[bool, str]:
+    """Verify if available memory is sufficient for model loading without triggering Android LMK."""
+    mem = get_memory_info()
+    avail = mem["effective_available_mb"]
+    
+    # If memory info could not be determined at all (0 MB), pass with a note
+    if mem["effective_total_mb"] == 0:
+        return True, "Memory detection unavailable on host OS; bypassing pre-flight guard."
+
+    if avail < required_mb:
+        return False, (
+            f"Available memory ({avail} MB) is below the recommended threshold ({required_mb} MB). "
+            f"Please enable Samsung RAM Plus (Settings -> Battery and device care -> Memory -> RAM Plus) "
+            f"or close background apps to avoid Low Memory Killer (LMK) termination."
+        )
+    return True, f"Memory check passed: {avail} MB available (RAM + zRAM)."
+
+
+class TermuxWakeLock:
+    """Context manager and controller to hold Android CPU WakeLock during long-running tasks."""
+    
+    def __init__(self, enabled: bool = True, fail_silently: bool = True):
+        self.enabled = enabled
+        self.fail_silently = fail_silently
+        self._acquired = False
+
+    def acquire(self) -> bool:
+        """Acquire CPU WakeLock via Termux API or direct Android Service Intent."""
+        if not self.enabled or not is_android_termux():
+            return False
+
+        # Boost process niceness to highest priority
+        try:
+            os.nice(-20)
+            logger.info("[TermuxWakeLock] Process niceness boosted to highest priority (-20)")
+        except Exception:
+            try:
+                os.nice(-10)
+            except Exception:
+                pass
+
+        wake_lock_bin = shutil.which("termux-wake-lock") or "/data/data/com.termux/files/usr/bin/termux-wake-lock"
+        if os.path.exists(wake_lock_bin):
+            try:
+                res = subprocess.run([wake_lock_bin], capture_output=True, timeout=3.0, check=False)
+                self._acquired = (res.returncode == 0)
+                if self._acquired:
+                    logger.info("[TermuxWakeLock] Acquired Termux CPU WakeLock via binary.")
+                return self._acquired
+            except Exception as e:
+                logger.debug("Exception while acquiring WakeLock via binary: %s", e)
+
+        # Robust fallback: invoke TermuxService wake_lock intent directly
+        try:
+            res = subprocess.run(
+                ["am", "startservice", "--user", "0", "-a", "com.termux.service_wake_lock", "com.termux/.app.TermuxService"],
+                capture_output=True, timeout=3.0, check=False
+            )
+            self._acquired = (res.returncode == 0)
+            if self._acquired:
+                logger.info("[TermuxWakeLock] Acquired Termux CPU WakeLock via TermuxService Intent.")
+            return self._acquired
+        except Exception as e:
+            if not self.fail_silently:
+                raise
+            logger.debug("Exception while acquiring WakeLock via Intent: %s", e)
+        return False
+
+    def release(self) -> bool:
+        """Release CPU WakeLock via Termux API or direct Android Service Intent."""
+        if self._acquired:
+            wake_unlock_bin = shutil.which("termux-wake-unlock") or "/data/data/com.termux/files/usr/bin/termux-wake-unlock"
+            if os.path.exists(wake_unlock_bin):
+                try:
+                    res = subprocess.run([wake_unlock_bin], capture_output=True, timeout=3.0, check=False)
+                    self._acquired = False
+                    if res.returncode == 0:
+                        logger.info("[TermuxWakeLock] Released Termux CPU WakeLock via binary.")
+                    return (res.returncode == 0)
+                except Exception as e:
+                    logger.debug("Exception while releasing WakeLock via binary: %s", e)
+
+            # Robust fallback: invoke TermuxService wake_unlock intent directly
+            try:
+                res = subprocess.run(
+                    ["am", "startservice", "--user", "0", "-a", "com.termux.service_wake_unlock", "com.termux/.app.TermuxService"],
+                    capture_output=True, timeout=3.0, check=False
+                )
+                self._acquired = False
+                if res.returncode == 0:
+                    logger.info("[TermuxWakeLock] Released Termux CPU WakeLock via TermuxService Intent.")
+                return (res.returncode == 0)
+            except Exception as e:
+                if not self.fail_silently:
+                    raise
+                logger.debug("Exception while releasing WakeLock via Intent: %s", e)
+            self._acquired = False
+        return False
+
+    def __enter__(self) -> "TermuxWakeLock":
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.release()
+

termux_diffusion/purger.py

@@ -0,0 +1,145 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""Clean-Room Purger module for terminating non-essential memory hogs.
+
+Strictly preserves critical system daemons, user shells, SSH sessions, and multiplexers
+while reclaiming physical RAM from zombie or idle inference processes before model loading.
+Operates exclusively as an opt-in CLI flag (--kill [threshold_mb]).
+"""
+
+import logging
+import os
+import signal
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Set, Tuple
+
+logger = logging.getLogger("termux_diffusion.purger")
+
+# 절대 불사 화이트리스트: 사용자 원격 세션 및 OS 필수 프로세스 영구 보호
+IMMORTAL_WHITELIST_COMM: Set[str] = {
+    "sshd",
+    "bash",
+    "sh",
+    "zsh",
+    "fish",
+    "tmux",
+    "tmux: server",
+    "screen",
+    "tailscaled",
+    "tailscale",
+    "init",
+    "zygote",
+    "zygote64",
+    "system_server",
+}
+
+
+@dataclass
+class ProcessKillRecord:
+    pid: int
+    name: str
+    rss_mb: float
+
+
+@dataclass
+class PurgeSummary:
+    threshold_mb: float
+    scanned_count: int
+    killed_processes: List[ProcessKillRecord] = field(default_factory=list)
+
+    @property
+    def total_reclaimed_mb(self) -> float:
+        return round(sum(p.rss_mb for p in self.killed_processes), 1)
+
+
+def get_process_rss_mb(pid: int) -> float:
+    """Read RSS memory deterministically from /proc/[pid]/statm in MB."""
+    statm_path = Path(f"/proc/{pid}/statm")
+    if not statm_path.exists():
+        return 0.0
+    try:
+        with open(statm_path, "r", encoding="utf-8") as f:
+            parts = f.readline().split()
+            if len(parts) >= 2:
+                # 2nd field is resident pages. 1 page = 4096 bytes on ARM64 Linux.
+                resident_pages = int(parts[1])
+                return round((resident_pages * 4096) / (1024 * 1024), 2)
+    except (FileNotFoundError, ProcessLookupError, PermissionError):
+        return 0.0
+    return 0.0
+
+
+def get_process_comm(pid: int) -> str:
+    """Read executable name deterministically from /proc/[pid]/comm."""
+    comm_path = Path(f"/proc/{pid}/comm")
+    if not comm_path.exists():
+        return ""
+    try:
+        with open(comm_path, "r", encoding="utf-8") as f:
+            return f.readline().strip()
+    except (FileNotFoundError, ProcessLookupError, PermissionError):
+        return ""
+
+
+def purge_idle_processes(threshold_mb: float = 50.0) -> PurgeSummary:
+    """Scan and terminate processes exceeding threshold_mb, preserving whitelist."""
+    self_pid = os.getpid()
+    self_ppid = os.getppid()
+    proc_dir = Path("/proc")
+    summary = PurgeSummary(threshold_mb=threshold_mb, scanned_count=0)
+
+    if not proc_dir.exists():
+        logger.warning("/proc filesystem not accessible. Clean-room purge aborted.")
+        return summary
+
+    targets_to_terminate: List[Tuple[int, str, float]] = []
+
+    for entry in proc_dir.iterdir():
+        if not entry.is_dir() or not entry.name.isdigit():
+            continue
+
+        pid = int(entry.name)
+        summary.scanned_count += 1
+
+        # 1. 자기 자신 및 직속 부모 프로세스 영구 보호
+        if pid == self_pid or pid == self_ppid:
+            continue
+
+        comm = get_process_comm(pid)
+
+        # 2. 불사 화이트리스트 보호
+        if comm in IMMORTAL_WHITELIST_COMM:
+            continue
+
+        # 3. RSS 측정 및 임계치 검사
+        rss_mb = get_process_rss_mb(pid)
+        if rss_mb >= threshold_mb:
+            targets_to_terminate.append((pid, comm, rss_mb))
+
+    # 프로세스 종료 실행: SIGTERM 전송 후 0.5초 대기, 생존 시 SIGKILL 단행
+    for pid, comm, rss_mb in targets_to_terminate:
+        try:
+            logger.info("Purging process %d (%s) consuming %.1f MB", pid, comm, rss_mb)
+            os.kill(pid, signal.SIGTERM)
+        except (ProcessLookupError, PermissionError):
+            continue
+
+    if targets_to_terminate:
+        time.sleep(0.5)
+
+    for pid, comm, rss_mb in targets_to_terminate:
+        try:
+            # 여전히 생존해 있는지 확인 (0 시그널 프로빙)
+            os.kill(pid, 0)
+            logger.warning("Process %d (%s) still alive, escalating to SIGKILL", pid, comm)
+            os.kill(pid, signal.SIGKILL)
+            summary.killed_processes.append(ProcessKillRecord(pid=pid, name=comm, rss_mb=rss_mb))
+        except ProcessLookupError:
+            # 정상 종료됨
+            summary.killed_processes.append(ProcessKillRecord(pid=pid, name=comm, rss_mb=rss_mb))
+        except PermissionError:
+            pass
+
+    return summary

termux_diffusion/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.