amv-diffusion 2.1.0__py3-none-any.whl

termux_diffusion/cluster.py

@@ -0,0 +1,340 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+AMEVA Unified Distributed RPC Cluster Orchestration Utility.
+Strict Protocol: Zero-Silent-Fallback & Zero-Deception ABI.
+Component: [DIFFUSION-CLUSTER]
+"""
+
+import socket
+import logging
+import time
+from typing import List, Optional, Union, Dict, Any, Callable, Set, Tuple
+
+from termux_diffusion.exceptions import (
+    ClusterConnectionError,
+    ClusterConfigurationError,
+    ClusterLicenseRequiredError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def check_cluster_license(license_key: Optional[str] = None) -> None:
+    """Enforces exclusive AMEVA-Cluster runtime license requirement.
+    Fail-Fast: Raises ClusterLicenseRequiredError if ameva_cluster is not installed
+    or license verification fails.
+    """
+    try:
+        from ameva_cluster.guard import verify_cluster_license
+    except ImportError:
+        raise ClusterLicenseRequiredError()
+
+    if not verify_cluster_license(license_key):
+        raise ClusterLicenseRequiredError(
+            "\n================================================================================\n"
+            "[AMEVA-CLUSTER] CLUSTER LICENSE INVALID (E403)\n"
+            "================================================================================\n"
+            "The provided AMEVA Cluster license token is invalid or expired.\n"
+            "Please check your AMEVA_CLUSTER_LICENSE environment variable.\n"
+            "================================================================================"
+        )
+
+
+def setup_cluster_guard_tunnels(
+    servers: List[str],
+    secret_key: Optional[str] = None
+) -> Tuple[List[str], List[Any]]:
+    """Establishes authenticated loopback MasterTunnels for remote RPC nodes.
+
+    Transforms remote endpoints into local authenticated tunnel endpoints (127.0.0.1:PORT)
+    which transparently inject the AMEVA Guard cryptographic handshake.
+
+    Returns:
+        Tuple of (tunnel_server_endpoints, active_tunnel_instances)
+    """
+    if not servers:
+        return [], []
+
+    try:
+        from ameva_cluster.guard import MasterTunnel
+    except ImportError:
+        raise ClusterLicenseRequiredError()
+
+    tunnel_endpoints: List[str] = []
+    active_tunnels: List[Any] = []
+
+    for endpoint in servers:
+        host, port_str = endpoint.split(":")
+        port = int(port_str)
+
+        # Local loopback addresses do not require an extra proxy hop
+        if host in ("127.0.0.1", "localhost", "::1"):
+            tunnel_endpoints.append(endpoint)
+            continue
+
+        tunnel = MasterTunnel(remote_host=host, remote_port=port, secret_key=secret_key)
+        tunnel.start()
+        active_tunnels.append(tunnel)
+        local_ep = f"127.0.0.1:{tunnel.local_port}"
+        tunnel_endpoints.append(local_ep)
+        logger.info(
+            "[AMEVA-DIFFUSION-CLUSTER] Authenticated MasterTunnel active: %s -> %s",
+            local_ep,
+            endpoint,
+        )
+
+    return tunnel_endpoints, active_tunnels
+
+
+
+def parse_cluster_rpc_spec(rpc_input: Optional[Union[str, List[str]]]) -> List[str]:
+    """Parse and normalize distributed RPC server endpoints.
+
+    Supports comma-separated strings or list of host:port strings.
+    Validates port ranges and host syntax strictly without silent normalization.
+    """
+    if not rpc_input:
+        return []
+
+    if isinstance(rpc_input, str):
+        raw_servers = [s.strip() for s in rpc_input.split(",") if s.strip()]
+    elif isinstance(rpc_input, (list, tuple)):
+        raw_servers = [str(s).strip() for s in rpc_input if str(s).strip()]
+    else:
+        raise ClusterConfigurationError(
+            f"Invalid cluster_rpc_servers specification type: {type(rpc_input).__name__}. "
+            f"Expected comma-separated string or list of endpoints."
+        )
+
+    parsed_servers: List[str] = []
+    for entry in raw_servers:
+        if ":" not in entry:
+            raise ClusterConfigurationError(
+                f"Invalid RPC endpoint format '{entry}'. Expected 'host:port' format (e.g. '192.0.2.11:50052')."
+            )
+        parts = entry.split(":")
+        if len(parts) != 2:
+            raise ClusterConfigurationError(
+                f"Malformed RPC endpoint '{entry}'. Exactly one colon separator required."
+            )
+        host, port_str = parts[0].strip(), parts[1].strip()
+        if not host:
+            raise ClusterConfigurationError(f"Empty hostname/IP in RPC endpoint '{entry}'.")
+        try:
+            port = int(port_str)
+            if port < 1 or port > 65535:
+                raise ValueError()
+        except ValueError:
+            raise ClusterConfigurationError(
+                f"Invalid port number '{port_str}' in RPC endpoint '{entry}'. Must be integer 1..65535."
+            )
+        parsed_servers.append(f"{host}:{port}")
+
+    return parsed_servers
+
+
+def ensure_wakelock() -> bool:
+    """Acquires Termux system-level wakelock to prevent Android kernel Doze deep-sleep."""
+    wakelock_bin = "/data/data/com.termux/files/usr/bin/termux-wake-lock"
+    import os
+    import subprocess
+    if os.path.exists(wakelock_bin):
+        try:
+            res = subprocess.run([wakelock_bin], capture_output=True, timeout=2.0)
+            if res.returncode == 0:
+                logger.info("[AMEVA-CLUSTER] Termux WakeLock acquired successfully.")
+                return True
+        except Exception as exc:
+            logger.warning("[AMEVA-CLUSTER] Failed to acquire termux-wake-lock: %s", exc)
+    return False
+
+
+def resolve_auto_tensor_split(
+    rpc_spec: Optional[Union[str, List[str]]],
+    tensor_split: Optional[str] = None,
+    min_guardband_mb: int = 400
+) -> Tuple[List[str], Optional[str]]:
+    """Automatically compute optimal tensor split when tensor_split == 'auto'.
+    Preserves explicit tensor_split specifications without alteration.
+    """
+    servers = parse_cluster_rpc_spec(rpc_spec)
+    if not servers:
+        return [], tensor_split
+
+    if tensor_split and str(tensor_split).strip().lower() == "auto":
+        try:
+            from termux_ai_orchestrator.auto_split import resolve_auto_tensor_split as orch_resolve
+            return orch_resolve(servers, min_guardband_mb=min_guardband_mb)
+        except Exception as exc:
+            logger.warning("[AMEVA-CLUSTER] Auto-TS fallback to equal distribution: %s", exc)
+            # Safe equal distribution fallback
+            n_nodes = len(servers) + 1
+            equal_pct = int(100 // n_nodes)
+            remainder = 100 - (equal_pct * n_nodes)
+            splits = [equal_pct + remainder] + [equal_pct] * len(servers)
+            return servers, ",".join(str(s) for s in splits)
+
+    return servers, tensor_split
+
+
+def verify_rpc_cluster_nodes(servers: List[str], timeout: float = 3.0) -> None:
+    """Strictly verify TCP reachability of each RPC server prior to initiating inference graph.
+
+    Zero-Silent-Fallback: If ANY specified RPC worker is unreachable, this function raises
+    ClusterConnectionError immediately to prevent silent local CPU/GPU fallback degradation.
+    """
+    if not servers:
+        return
+
+    failed_nodes = []
+    for endpoint in servers:
+        host, port_str = endpoint.split(":")
+        port = int(port_str)
+        try:
+            with socket.create_connection((host, port), timeout=timeout):
+                logger.info("[AMEVA-CLUSTER] RPC Worker verified reachable: %s", endpoint)
+        except (socket.timeout, ConnectionRefusedError, OSError) as exc:
+            failed_nodes.append((endpoint, str(exc)))
+
+    if failed_nodes:
+        err_details = "\n".join([f"  - {ep}: {err}" for ep, err in failed_nodes])
+        raise ClusterConnectionError(
+            f"Distributed RPC Cluster Pre-Flight Check FAILED for {len(failed_nodes)}/{len(servers)} worker(s):\n"
+            f"{err_details}\n"
+            f"Zero-Silent-Fallback Violation Prevented: Inference terminated to avoid silent execution degradation."
+        )
+
+
+def verify_rpc_cluster_health(servers: List[str], timeout: float = 3.0) -> Dict[str, Any]:
+    """Inspect and report cluster connectivity status without throwing, returning granular diagnostics."""
+    status: Dict[str, Any] = {"all_healthy": True, "nodes": {}}
+    for endpoint in servers:
+        host, port_str = endpoint.split(":")
+        port = int(port_str)
+        try:
+            with socket.create_connection((host, port), timeout=timeout):
+                status["nodes"][endpoint] = {"status": "ONLINE", "error": None}
+        except Exception as exc:
+            status["all_healthy"] = False
+            status["nodes"][endpoint] = {"status": "OFFLINE", "error": str(exc)}
+    return status
+
+
+class ClusterOptionForwarder:
+    """Transparent option collector and pass-through forwarder for sub-engines.
+
+    Zero-Deception & Zero-Silent-Drop Principle:
+    Preserves all CLI arguments, keyword options, and custom engine parameters
+    without silent truncation, enabling seamless pass-through to underlying binaries
+    (sd-cli, llama-cli, whisper-cli, etc.) across distributed cluster nodes.
+    """
+
+    @staticmethod
+    def to_cli_flag(key: str) -> str:
+        """Convert snake_case Python identifier to --kebab-case CLI argument flag."""
+        clean_key = key.strip().replace("_", "-")
+        if not clean_key.startswith("-"):
+            clean_key = f"--{clean_key}"
+        return clean_key
+
+    @classmethod
+    def normalize_forward_args(
+        cls,
+        options: Dict[str, Any],
+        extra_args: Optional[List[str]] = None,
+        exclude_keys: Optional[Union[List[str], set]] = None,
+    ) -> List[str]:
+        """Convert a dictionary of engine options into an argv argument list,
+        losslessly preserving raw extra arguments at the end.
+        """
+        exclude = set(exclude_keys or [])
+        cmd_args: List[str] = []
+
+        for k, v in options.items():
+            if k in exclude or v is None:
+                continue
+
+            flag = cls.to_cli_flag(k)
+
+            if isinstance(v, bool):
+                if v:
+                    cmd_args.append(flag)
+            elif isinstance(v, (list, tuple)):
+                for item in v:
+                    cmd_args.extend([flag, str(item)])
+            else:
+                cmd_args.extend([flag, str(v)])
+
+        if extra_args:
+            for arg in extra_args:
+                if str(arg).strip():
+                    cmd_args.append(str(arg).strip())
+
+        return cmd_args
+
+    @classmethod
+    def merge_pass_through_args(
+        cls,
+        base_cmd: List[str],
+        extra_args: Optional[List[str]] = None,
+        overrides: Optional[Dict[str, Any]] = None,
+    ) -> List[str]:
+        """Merge base command with pass-through extra arguments and key-value overrides."""
+        merged = list(base_cmd)
+        if overrides:
+            override_args = cls.normalize_forward_args(overrides)
+            merged.extend(override_args)
+        if extra_args:
+            for a in extra_args:
+                if str(a).strip():
+                    merged.append(str(a).strip())
+        return merged
+
+
+class SequentialClusterPipeline:
+    """Two-Stage Memory Isolation Pipeline for Mobile On-Device AI Clustering.
+
+    Architecture (Text-Encode-Then-Kill -> Disaggregated DiT Inference):
+    - Stage 1 (Text Encoding Phase): Spawns isolated subprocess for LLM/CLIP text encoding.
+      Generates prompt embeddings/cache, then immediately terminates and kills the process
+      to return 100% of the allocated memory (~1.7GB) to the Android kernel.
+    - Stage 2 (Disaggregated DiT Sampling Phase): Launches diffusion backbone inference
+      in clean RAM environment, losslessly forwarding all distributed RPC cluster flags
+      (--rpc-servers, -ts, --schedule, --flow-shift, etc.) to remote workers.
+    """
+
+    def __init__(self, forwarder: Optional[ClusterOptionForwarder] = None):
+        self.forwarder = forwarder or ClusterOptionForwarder()
+
+    def execute_stages(
+        self,
+        prompt: str,
+        stage1_fn: Callable[[], Any],
+        stage2_fn: Callable[[], Any],
+    ) -> Any:
+        """Execute Stage 1 and Stage 2 sequentially with strict fail-fast enforcement."""
+        ensure_wakelock()
+        logger.info("[AMEVA-CLUSTER] Initiating Sequential 2-Stage Memory Isolation Pipeline...")
+        t0 = time.time()
+
+        # Stage 1: Text Encoding with memory recovery guarantee
+        logger.info("[AMEVA-CLUSTER] [Stage 1/2] Executing Isolated Text Encoding Phase...")
+        try:
+            stage1_result = stage1_fn()
+            logger.info("[AMEVA-CLUSTER] [Stage 1/2] Text Encoding completed. Reclaiming memory.")
+        except Exception as e:
+            logger.error("[AMEVA-CLUSTER] [Stage 1/2] Text Encoding failed: %s", e)
+            raise
+
+        # Stage 2: Disaggregated DiT Sampling & Decoding
+        logger.info("[AMEVA-CLUSTER] [Stage 2/2] Launching Distributed DiT Inference in clean RAM...")
+        try:
+            stage2_result = stage2_fn()
+            elapsed = time.time() - t0
+            logger.info("[AMEVA-CLUSTER] 2-Stage Sequential Inference succeeded in %.2fs", elapsed)
+            return stage2_result
+        except Exception as e:
+            logger.error("[AMEVA-CLUSTER] [Stage 2/2] Distributed DiT Inference failed: %s", e)
+            raise
+

termux_diffusion/control/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""termux_diffusion.control — AMEVA Component Protocol v1."""
+from .component import DiffusionControl
+__all__ = ["DiffusionControl"]

termux_diffusion/control/component.py

@@ -0,0 +1,309 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+termux_diffusion.control.component
+AMEVA Component Protocol v1 — DiffusionControl
+
+model_id는 파일명이 아닌 Pipeline Manifest를 가리킵니다.
+(UNet + VAE + Text Encoder + Tokenizer + Scheduler Config)
+기존 installer.run_doctor() + hub.py를 Adapter로 연결합니다.
+"""
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from ameva_component import (
+    ActivationLock, ComponentInfo, ComponentStateFile,
+    ControlMode, InstanceRegistry, InstanceState, InstanceStatus,
+    ModelRegistry, ModelState, ModelNotFound, ModelLoadFailed,
+    OperationNotSupported, now_timestamps, log_stderr, PROTOCOL_COMPONENT,
+)
+from ameva_component.control import ComponentControl
+
+
+class DiffusionControl(ComponentControl):
+    """
+    termux-diffusion ComponentControl.
+
+    model_id = Pipeline Manifest ID (단일 파일명 아님).
+    기존 installer.run_doctor(), hub.DEFAULT_PRESETS를 Adapter로 연결.
+    """
+
+    COMPONENT_ID   = "termux-diffusion"
+    COMPONENT_TYPE = "diffusion"
+    CAPABILITIES   = ("image.generate",)
+
+    DEFAULT_MODELS_DIR = Path.home() / ".cache" / "termux-diffusion" / "models"
+
+    def __init__(self, models_dir: Path | None = None) -> None:
+        self._models_dir = models_dir or self.DEFAULT_MODELS_DIR
+        self._state_file = ComponentStateFile(self.COMPONENT_ID)
+        self._model_reg  = ModelRegistry(self.COMPONENT_ID)
+        self._inst_reg   = InstanceRegistry(self.COMPONENT_ID)
+        self._act_lock   = ActivationLock()
+        # Phase 4: Heartbeat Writer
+        from termux_diffusion.control.status import DiffusionStatusWriter
+        self._heartbeat = DiffusionStatusWriter(self)
+
+    def _get_version(self) -> str:
+        try:
+            from termux_diffusion import __version__; return __version__
+        except Exception: return "1.3.2"
+
+    def component_info(self) -> dict:
+        info = ComponentInfo(
+            protocol=PROTOCOL_COMPONENT, component_id=self.COMPONENT_ID,
+            component_type=self.COMPONENT_TYPE, version=self._get_version(),
+            capabilities=self.CAPABILITIES,
+        )
+        info.validate()
+        return info.to_dict()
+
+    def doctor_lite(self) -> dict:
+        """
+        경량 진단.
+        샘플 추론 금지, 엔진 바이너리 존재 여부 + 상태파일만.
+        """
+        ts = now_timestamps()
+        state_data = self._state_file.read()
+        stale = self._state_file.is_stale(threshold_ms=30_000)
+        pid_info = self._check_pid()
+        pid = pid_info.get("pid")
+        pid_alive = pid_info.get("alive")
+        instances = self._inst_reg.list_all()
+        hot = [i for i in instances if i.state == InstanceState.HOT]
+
+        # 엔진 바이너리 존재 여부 (실행 금지)
+        engine_present = self._check_engine_binary()
+
+        ready = engine_present
+        degraded = stale or not engine_present or (pid_alive is not True)
+
+        proc_dict: dict[str, Any] = {
+            "running": pid_alive,
+            "pid": pid,
+            "verified": pid_info.get("verified", False),
+        }
+        if "inspection_error" in pid_info:
+            proc_dict["inspection_error"] = pid_info["inspection_error"]
+        if "reason" in pid_info:
+            proc_dict["reason"] = pid_info["reason"]
+
+        return {
+            "protocol": "ameva-component-status/1",
+            "component_id": self.COMPONENT_ID, "component_type": self.COMPONENT_TYPE,
+            "version": self._get_version(), "ready": ready, "degraded": degraded,
+            **ts,
+            "process": proc_dict,
+            "capabilities": list(self.CAPABILITIES),
+            "active_models": [i.model_id for i in hot],
+            "engine": {"present": engine_present},
+            "instances": [{"instance_id": i.instance_id, "model_id": i.model_id,
+                           "state": i.state.value, "active_jobs": i.active_jobs} for i in instances],
+            "errors": [state_data.get("last_error")] if state_data and state_data.get("last_error") else [],
+            "state_file": {"path": str(self._state_file.path), "stale": stale,
+                           "updated_at": state_data.get("updated_at") if state_data else None},
+        }
+
+    # DEFAULT_PID_FILE: COMPONENT_ID 기반 표준 경로
+    DEFAULT_PID_FILE: Path = Path.home() / ".local" / "run" / "termux-diffusion.pid"
+
+    def _check_pid(self) -> dict[str, Any]:
+        """BLOCKER 1: PID 파일에서 sd-cli 프로세스 생존 여부 확인.
+        PermissionError/OSError 발생 시 alive=None, verified=False, inspection_error 반환."""
+        import logging
+        _log = logging.getLogger(__name__)
+
+        if self.DEFAULT_PID_FILE.exists():
+            try:
+                raw = self.DEFAULT_PID_FILE.read_text().strip()
+                pid = int(raw)
+            except (ValueError, OSError) as parse_err:
+                _log.warning("[diffusion] PID file parse/read error: %s", parse_err)
+                return {
+                    "pid": None,
+                    "alive": None,
+                    "verified": False,
+                    "inspection_error": {
+                        "code": "PID_PARSE_ERROR",
+                        "message": str(parse_err),
+                    },
+                }
+
+            try:
+                os.kill(pid, 0)
+                return {"pid": pid, "alive": True, "verified": True}
+            except ProcessLookupError:
+                return {
+                    "pid": pid,
+                    "alive": False,
+                    "verified": True,
+                    "reason": "process_lookup_failed",
+                }
+            except PermissionError as perm_err:
+                _log.warning("[diffusion] PID %s alive check PermissionError: %s", pid, perm_err)
+                return {
+                    "pid": pid,
+                    "alive": None,
+                    "verified": False,
+                    "inspection_error": {
+                        "code": "PROCESS_INSPECTION_PERMISSION_DENIED",
+                        "message": str(perm_err),
+                    },
+                }
+            except OSError as os_err:
+                _log.warning("[diffusion] PID %s alive check OSError: %s", pid, os_err)
+                return {
+                    "pid": pid,
+                    "alive": None,
+                    "verified": False,
+                    "inspection_error": {
+                        "code": "PROCESS_INSPECTION_OS_ERROR",
+                        "message": str(os_err),
+                    },
+                }
+        return {
+            "pid": None,
+            "alive": False,
+            "verified": True,
+            "reason": "pid_file_missing",
+        }
+
+
+
+    def _check_engine_binary(self) -> bool:
+        """엔진 바이너리 존재 여부만 확인 — 실행 금지."""
+        try:
+            from termux_diffusion.installer import provision_engine
+            return True  # 모듈 import 성공 = 설치 가능 상태
+        except ImportError:
+            return False  # Allowed: engine not installed -> binary check fails-closed.
+
+    def doctor_full(self) -> dict:
+        """기존 installer.run_doctor() 전체 실행."""
+        lite = self.doctor_lite()
+        try:
+            from termux_diffusion.installer import run_doctor
+            result = run_doctor()
+            lite["full_doctor"] = result if isinstance(result, dict) else {"output": str(result)}
+        except Exception as e:
+            lite["doctor_error"] = str(e)
+        lite["doctor_level"] = "full"
+        return lite
+
+    def list_models(self) -> dict:
+        """Pipeline Manifest 기반 모델 목록 + hub.DEFAULT_PRESETS."""
+        reg_map = {m["model_id"]: m for m in self._model_reg.list_all()}
+        try:
+            from termux_diffusion.hub import DEFAULT_PRESETS, list_presets
+            for preset_id, preset_info in DEFAULT_PRESETS.items():
+                if preset_id not in reg_map:
+                    reg_map[preset_id] = {
+                        "model_id":    preset_id,
+                        "state":       "missing",
+                        "format":      "pipeline",
+                        "note":        "Available preset — not yet downloaded",
+                        "description": str(preset_info),
+                        "verified_at": None,
+                    }
+        except Exception as e:
+            log_stderr(f"[diffusion] hub.DEFAULT_PRESETS load failed: {e}")
+        return {"models": list(reg_map.values()), "total": len(reg_map),
+                "models_dir": str(self._models_dir)}
+
+    def model_status(self, model_id: str | None = None) -> dict:
+        if model_id:
+            rec = self._model_reg.get(model_id)
+            if rec is None: raise ModelNotFound(model_id)
+            return {"model": rec}
+        return self.list_models()
+
+    def install_model(self, request: dict) -> dict:
+        """Pipeline Manifest 기반 설치 — 모든 구성 파일 Hash 검증."""
+        from ameva_component import ModelInstaller
+        url = request.get("url", ""); filename = request.get("filename", "")
+        sha256 = request.get("sha256", "")
+        expected_bytes = int(request.get("expected_bytes", 0))
+        model_id = request.get("model_id") or Path(filename).stem
+        self._models_dir.mkdir(parents=True, exist_ok=True)
+        installer = ModelInstaller(self.COMPONENT_ID, self._models_dir, self._model_reg)
+        return installer.install(url=url, filename=filename, sha256=sha256,
+                                 expected_bytes=expected_bytes, model_id=model_id,
+                                 after_download=self._verify_pipeline_file)
+
+    def _verify_pipeline_file(self, path: Path) -> None:
+        """Pipeline 구성 파일 기본 형식 확인 — 추론 실행 금지."""
+        valid = {".safetensors", ".bin", ".json", ".onnx", ".pt"}
+        if path.suffix.lower() not in valid:
+            raise ValueError(f"Unexpected pipeline file format: '{path.suffix}'")
+
+    async def activate_model(self, request: dict) -> dict:
+        model_id = request.get("model_id", "")
+        rec = self._model_reg.get(model_id)
+        if rec is None: raise ModelNotFound(model_id)
+        if ModelState.from_str(rec.get("state", "missing")) not in (ModelState.INSTALLED, ModelState.INACTIVE):
+            raise ModelLoadFailed(model_id, f"Pipeline state is '{rec.get('state')}'")
+        with self._act_lock.acquire(timeout=60.0):
+            self._model_reg.set_state(model_id, ModelState.ACTIVE)
+            self._write_state()
+        return {"activated": True, "model_id": model_id,
+                "rollback": {"attempted": False, "succeeded": False}}
+
+    async def deactivate_model(self, request: dict) -> dict:
+        model_id = request.get("model_id", "")
+        self._model_reg.set_state(model_id, ModelState.INACTIVE)
+        self._write_state()
+        return {"deactivated": True, "model_id": model_id}
+
+    def list_instances(self) -> dict:
+        instances = self._inst_reg.list_all()
+        return {"instances": [i.to_dict() for i in instances], "total": len(instances)}
+
+    async def start_instance(self, request: dict) -> dict:
+        model_id = request.get("model_id", "")
+        instance_id = request.get("instance_id") or f"diffusion-worker-{int(time.time())}"
+        inst = InstanceStatus(
+            instance_id=instance_id, component_id=self.COMPONENT_ID,
+            model_id=model_id, state=InstanceState.HOT,
+            active_jobs=0, queue_depth=0, max_concurrency=1,
+            backend="cpu", started_at=time.time(), last_heartbeat=time.time(),
+            last_error=None, control_mode=ControlMode.IN_PROCESS,
+        )
+        self._inst_reg.register(inst)
+        self._write_state()
+        # Phase 4: Heartbeat 시작 (Worker 시작 트리거)
+        self._heartbeat.start()
+        return {"instance_id": instance_id, "state": InstanceState.HOT.value}
+
+    async def drain_instance(self, instance_id: str) -> dict:
+        from ameva_component import InstanceNotFound
+        if not self._inst_reg.get(instance_id): raise InstanceNotFound(instance_id)
+        self._inst_reg.update_state(instance_id, InstanceState.DRAINING)
+        return {"instance_id": instance_id, "state": InstanceState.DRAINING.value}
+
+    async def stop_instance(self, instance_id: str) -> dict:
+        from ameva_component import InstanceNotFound
+        if not self._inst_reg.get(instance_id): raise InstanceNotFound(instance_id)
+        self._inst_reg.update_state(instance_id, InstanceState.STOPPED)
+        self._inst_reg.remove(instance_id)
+        # Phase 4: Heartbeat 중단 (정상 종료 트리거)
+        remaining = self._inst_reg.list_all()
+        if not remaining:
+            self._heartbeat.stop()
+        else:
+            self._write_state()
+        return {"instance_id": instance_id, "state": InstanceState.STOPPED.value}
+
+    def _write_state(self, *, ready: bool | None = None, last_error: str | None = None) -> None:
+        ts = now_timestamps()
+        hot = [i for i in self._inst_reg.list_all() if i.state == InstanceState.HOT]
+        _, pid_alive = self._check_pid()
+        _ready = self._check_engine_binary() if ready is None else ready
+        self._state_file.write({
+            "protocol": "ameva-component-status/1", "component_id": self.COMPONENT_ID,
+            "component_type": self.COMPONENT_TYPE, "version": self._get_version(),
+            "ready": _ready, "degraded": not _ready, **ts,
+            "active_models": [i.model_id for i in hot], "last_error": last_error,
+        })

termux_diffusion/control/status.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+termux_diffusion.control.status — Diffusion 상태 파일 Writer + Heartbeat
+"""
+from __future__ import annotations
+from typing import Any
+from ameva_component.heartbeat import HeartbeatWriter
+
+
+class DiffusionStatusWriter(HeartbeatWriter):
+    """DiffusionControl 상태를 10초마다 상태 파일에 원자적으로 기록합니다."""
+
+    def __init__(self, control: Any) -> None:
+        super().__init__(control, name="diffusion")