ltcai 4.2.0 → 4.3.1

package/latticeai/services/agent_runtime.py

@@ -50,6 +50,10 @@ def _now() -> str:
     return datetime.now().isoformat(timespec="seconds")
 
 
+class AgentRuntimeUnavailable(RuntimeError):
+    """Raised when a product run would otherwise persist simulation output."""
+
+
 class AgentRuntime:
     def __init__(
         self,
@@ -60,6 +64,7 @@ class AgentRuntime:
         append_audit_event: Callable[..., None],
         max_retries_cap: int = 5,
         hooks: Any = None,
+        allow_simulation_runs: bool = False,
     ):
         self._store = store
         self._orchestrator_factory = orchestrator_factory
@@ -69,6 +74,7 @@ class AgentRuntime:
         # Lifecycle hooks registry (optional). When present, ``start`` fires the
         # ``pre_run`` / ``post_run`` hooks; a blocking ``pre_run`` aborts the run.
         self._hooks = hooks
+        self._allow_simulation_runs = bool(allow_simulation_runs)
         self._run_executor: Any = None
 
     def attach_executor(self, executor: Any) -> None:
@@ -85,6 +91,7 @@ class AgentRuntime:
             "default_pipeline": list(CORE_PIPELINE),
             "max_retries_cap": self._max_retries_cap,
             "execution_mode": self._execution_mode(),
+            "simulation_runs_allowed": self._allow_simulation_runs,
             "cancellation": (
                 "cooperative; running synchronous model/tool calls finish their current step before a cancelled status is persisted"
                 if self._run_executor is not None else
@@ -107,6 +114,7 @@ class AgentRuntime:
     def health(self) -> Dict[str, Any]:
         checks: Dict[str, Any] = {}
         ok = True
+        ready = True
         try:
             self._store.list_agents(workspace_id=None)
             checks["run_store"] = {"status": "ok"}
@@ -114,12 +122,42 @@ class AgentRuntime:
             ok = False
             checks["run_store"] = {"status": "error", "detail": str(exc)}
         try:
-            self._orchestrator_factory(None, None)
-            checks["orchestrator"] = {"status": "ok"}
+            orchestrator = self._orchestrator_factory(None, None)
+            mode = getattr(orchestrator, "mode", "simulation")
+            if mode == "simulation":
+                if self._allow_simulation_runs:
+                    checks["orchestrator"] = {
+                        "status": "ok",
+                        "mode": mode,
+                        "detail": "Simulation runs are explicitly enabled for this non-product runtime.",
+                    }
+                else:
+                    ready = False
+                    checks["orchestrator"] = {
+                        "status": "unavailable",
+                        "mode": mode,
+                        "detail": "No LLM-backed model is loaded; product execution API refuses simulation runs.",
+                    }
+            else:
+                checks["orchestrator"] = {"status": "ok", "mode": mode}
         except Exception as exc:  # pragma: no cover - defensive
             ok = False
             checks["orchestrator"] = {"status": "error", "detail": str(exc)}
-        return {"status": "ok" if ok else "degraded", "checks": checks}
+        return {
+            "status": "ok" if ok and ready else "unavailable" if ok else "degraded",
+            "ready": bool(ok and ready),
+            "checks": checks,
+        }
+
+    def _live_orchestrator(self, user_email: Optional[str], scope: Optional[str]) -> Any:
+        orchestrator = self._orchestrator_factory(user_email or None, scope)
+        mode = getattr(orchestrator, "mode", "simulation")
+        if mode == "simulation" and not self._allow_simulation_runs:
+            raise AgentRuntimeUnavailable(
+                "Agent execution is unavailable because no LLM-backed model is loaded. "
+                "Simulation mode is disabled in the product execution API so it cannot be recorded as real success."
+            )
+        return orchestrator
 
     # ── roster + status ───────────────────────────────────────────────────
     def _roster(self, runs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
@@ -163,16 +201,21 @@ class AgentRuntime:
             listing = {"agents": [], "runs": [], "error": str(exc)}
         runs = list(listing.get("runs") or [])
         active = sum(1 for r in runs if str(r.get("status")) in _ACTIVE_STATUSES)
+        health = self.health()
+        orchestrator_status = (health.get("checks") or {}).get("orchestrator") or {}
+        ready = bool(health.get("ready"))
         return {
             "runtime": {
-                "ready": True,
+                "ready": ready,
                 "version": MULTI_AGENT_VERSION,
                 "execution_mode": self._execution_mode(),
+                "mode": orchestrator_status.get("mode", "unknown"),
+                "unavailable_reason": None if ready else orchestrator_status.get("detail"),
                 "default_pipeline": list(CORE_PIPELINE),
                 "total_runs": len(runs),
                 "active_runs": active,
             },
-            "health": self.health(),
+            "health": health,
             "roles": self.roles(),
             "agents": self._roster(runs),
             "runs": runs[:25],
@@ -288,11 +331,8 @@ class AgentRuntime:
             user_email=user_email,
             scope=scope,
         )
-        try:
-            orchestrator = self._orchestrator_factory(user_email or None, scope)
-            mode = getattr(orchestrator, "mode", "simulation")
-        except Exception:
-            mode = "simulation"
+        orchestrator = self._live_orchestrator(user_email, scope)
+        mode = getattr(orchestrator, "mode", "llm")
         run = self._store.record_agent_run(
             agent_id=ROLE_AGENT_IDS.get("executor", "agent:executor"),
             status="queued",
@@ -349,7 +389,7 @@ class AgentRuntime:
             started_at=run.get("started_at") or _now(),
         )
         try:
-            orchestrator = self._orchestrator_factory(user_email or None, scope)
+            orchestrator = self._live_orchestrator(user_email, scope)
             result = orchestrator.run(
                 goal,
                 user_email=user_email or None,
@@ -452,7 +492,7 @@ class AgentRuntime:
                 )
                 raise PermissionError(pre_dispatch.get("block_reason") or "Agent run blocked by a pre_run hook.")
 
-        orchestrator = self._orchestrator_factory(user_email or None, scope)
+        orchestrator = self._live_orchestrator(user_email, scope)
         result = orchestrator.run(
             goal,
             user_email=user_email or None,

package/latticeai/services/kg_portability.py

@@ -19,7 +19,7 @@ import shutil
 import tempfile
 import zipfile
 from datetime import datetime, timezone
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any, Dict, Optional
 
 from lattice_brain.archive import BrainArchivePaths, EncryptedBrainArchive
@@ -50,6 +50,13 @@ def _sha256_file(path: Path) -> str:
     return h.hexdigest()
 
 
+def _safe_zip_names(names) -> None:
+    for name in names:
+        path = PurePosixPath(name)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"Backup archive contains unsafe path: {name}")
+
+
 class KGPortabilityService:
     def __init__(self, *, knowledge_graph: Any, data_dir, enable_graph: bool = True, device_identity: Any = None) -> None:
         self._kg = knowledge_graph
@@ -156,13 +163,23 @@ class KGPortabilityService:
                             zf.write(f, f"blobs/{f.relative_to(blob_dir)}")
         return {"path": str(dest), "bytes": dest.stat().st_size, "manifest": manifest}
 
-    def restore(self, archive_path, *, verify: bool = True) -> Dict[str, Any]:
+    def restore(
+        self,
+        archive_path,
+        *,
+        verify: bool = True,
+        dry_run: bool = False,
+        confirm: bool = False,
+    ) -> Dict[str, Any]:
         self._require()
         archive = Path(archive_path)
         if not archive.exists():
             raise FileNotFoundError(f"Backup archive not found: {archive}")
+        if not dry_run and not confirm:
+            raise ValueError("Explicit confirmation is required before restoring a Knowledge Graph backup.")
         with zipfile.ZipFile(archive) as zf:
             names = zf.namelist()
+            _safe_zip_names(names)
             if "knowledge_graph.sqlite" not in names:
                 raise ValueError("Archive is missing knowledge_graph.sqlite.")
             manifest = json.loads(zf.read("manifest.json")) if "manifest.json" in names else {}
@@ -173,6 +190,18 @@ class KGPortabilityService:
                 if verify and manifest.get("db_sha256"):
                     if _sha256_file(db_src) != manifest["db_sha256"]:
                         raise ValueError("Backup integrity check failed (db sha256 mismatch).")
+                if dry_run:
+                    return {
+                        "restored": False,
+                        "dry_run": True,
+                        "verified": True,
+                        "manifest": manifest,
+                        "planned": {
+                            "database": str(self._kg.db_path),
+                            "blobs": str(self._kg.blob_dir),
+                            "archive": str(archive),
+                        },
+                    }
                 db_dest = Path(self._kg.db_path)
                 blob_dest = Path(self._kg.blob_dir)
                 db_dest.parent.mkdir(parents=True, exist_ok=True)
@@ -196,25 +225,82 @@ class KGPortabilityService:
             "nodes": sum(stats.get("nodes", {}).values()),
         }
 
+    def verify_backup(self, archive_path) -> Dict[str, Any]:
+        archive = Path(archive_path)
+        if not archive.exists():
+            return {"ok": False, "path": str(archive), "errors": [f"Backup archive not found: {archive}"]}
+        try:
+            with zipfile.ZipFile(archive) as zf:
+                names = zf.namelist()
+                _safe_zip_names(names)
+                if "knowledge_graph.sqlite" not in names:
+                    raise ValueError("Archive is missing knowledge_graph.sqlite.")
+                manifest = json.loads(zf.read("manifest.json")) if "manifest.json" in names else {}
+                with tempfile.TemporaryDirectory() as tmp_s:
+                    tmp = Path(tmp_s)
+                    zf.extract("knowledge_graph.sqlite", tmp)
+                    db_src = tmp / "knowledge_graph.sqlite"
+                    if manifest.get("db_sha256") and _sha256_file(db_src) != manifest["db_sha256"]:
+                        raise ValueError("Backup integrity check failed (db sha256 mismatch).")
+            return {"ok": True, "path": str(archive), "manifest": manifest, "errors": []}
+        except (ValueError, zipfile.BadZipFile, OSError, json.JSONDecodeError) as exc:
+            return {"ok": False, "path": str(archive), "errors": [str(exc)]}
+
     # ── encrypted .latticebrain archive ───────────────────────────────────
     def encrypted_archive(self, dest_path=None, *, passphrase: str) -> Dict[str, Any]:
         self._require()
         self._exports_dir.mkdir(parents=True, exist_ok=True)
         dest = Path(dest_path) if dest_path else self._exports_dir / f"brain-{_stamp()}.latticebrain"
+        metadata = {
+            "storage": self.storage_status().get("active", {}),
+            "snapshot": self.snapshot_metadata(),
+            "device_identity": self._identity.describe() if self._identity is not None else {},
+            "provenance": {"exported_at": _now_iso(), "source": "kg-portability"},
+        }
         archive = EncryptedBrainArchive(
             BrainArchivePaths(
                 db_path=Path(self._kg.db_path),
                 blob_dir=Path(self._kg.blob_dir),
+                data_dir=self._data_dir,
+                metadata=metadata,
             )
         )
         return archive.create(dest, passphrase=passphrase)
 
-    def restore_encrypted_archive(self, archive_path, *, passphrase: str) -> Dict[str, Any]:
+    def inspect_encrypted_archive(self, archive_path, *, passphrase: Optional[str] = None) -> Dict[str, Any]:
+        archive = EncryptedBrainArchive(
+            BrainArchivePaths(
+                db_path=Path(self._kg.db_path),
+                blob_dir=Path(self._kg.blob_dir),
+                data_dir=self._data_dir,
+            )
+        )
+        return archive.inspect(Path(archive_path), passphrase=passphrase)
+
+    def verify_encrypted_archive(self, archive_path, *, passphrase: str) -> Dict[str, Any]:
+        archive = EncryptedBrainArchive(
+            BrainArchivePaths(
+                db_path=Path(self._kg.db_path),
+                blob_dir=Path(self._kg.blob_dir),
+                data_dir=self._data_dir,
+            )
+        )
+        return archive.verify(Path(archive_path), passphrase=passphrase)
+
+    def restore_encrypted_archive(
+        self,
+        archive_path,
+        *,
+        passphrase: str,
+        dry_run: bool = False,
+        confirm: bool = False,
+    ) -> Dict[str, Any]:
         self._require()
         archive = EncryptedBrainArchive(
             BrainArchivePaths(
                 db_path=Path(self._kg.db_path),
                 blob_dir=Path(self._kg.blob_dir),
+                data_dir=self._data_dir,
             )
         )
         return archive.restore(
@@ -223,9 +309,29 @@ class KGPortabilityService:
             target=BrainArchivePaths(
                 db_path=Path(self._kg.db_path),
                 blob_dir=Path(self._kg.blob_dir),
+                data_dir=self._data_dir,
             ),
+            dry_run=dry_run,
+            confirm=confirm,
         )
 
+    def import_encrypted_archive(
+        self,
+        archive_path,
+        *,
+        passphrase: str,
+        dry_run: bool = False,
+        confirm: bool = False,
+    ) -> Dict[str, Any]:
+        result = self.restore_encrypted_archive(
+            archive_path,
+            passphrase=passphrase,
+            dry_run=dry_run,
+            confirm=confirm,
+        )
+        result["operation"] = "import"
+        return result
+
     # ── status surface ───────────────────────────────────────────────────────
     def snapshot_metadata(self) -> Dict[str, Any]:
         if not self.available():
@@ -253,6 +359,28 @@ class KGPortabilityService:
                 else {"engine": "sqlite", "available": True}
             ),
             "postgres": PostgresEngine("", schema="lattice_brain").capabilities().as_dict(),
+            "backup_health": self.backup_health(),
+        }
+
+    def backup_health(self) -> Dict[str, Any]:
+        self._exports_dir.mkdir(parents=True, exist_ok=True)
+        backups = sorted(
+            [
+                p for p in self._exports_dir.glob("*")
+                if p.is_file() and (p.suffix == ".zip" or p.suffix == ".latticebrain")
+            ],
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        latest = backups[0] if backups else None
+        return {
+            "available": True,
+            "directory": str(self._exports_dir),
+            "count": len(backups),
+            "latest": str(latest) if latest else None,
+            "latest_bytes": latest.stat().st_size if latest else 0,
+            "encrypted_archives": sum(1 for p in backups if p.suffix == ".latticebrain"),
+            "zip_backups": sum(1 for p in backups if p.suffix == ".zip"),
         }
 
     def postgres_docker_setup(
@@ -279,7 +407,22 @@ class KGPortabilityService:
             Path(self._kg.db_path),
             PostgresEngine(dsn, schema=schema),
         )
-        return migrator.migrate(dry_run=dry_run)
+        if dry_run:
+            return migrator.migrate(dry_run=True)
+        backup = self.backup()
+        verification = self.verify_backup(backup["path"])
+        if not verification.get("ok"):
+            raise RuntimeError(
+                "Pre-migration backup verification failed; Postgres migration was not started: "
+                + "; ".join(verification.get("errors") or [])
+            )
+        result = migrator.migrate(dry_run=False)
+        result["pre_migration_backup"] = {
+            "path": backup["path"],
+            "verified": True,
+            "manifest": backup.get("manifest"),
+        }
+        return result
 
     def recent_ingestions(self, *, limit: int = 50, source_type: Optional[str] = None) -> Dict[str, Any]:
         """Recent provenance records (newest first) for the ingestion-sources UI."""

package/latticeai/services/model_runtime.py

@@ -66,6 +66,51 @@ IS_PUBLIC_MODE = False
 keyring = None
 
 
+def _env_bool(key: str, default: bool = False) -> bool:
+    raw = os.getenv(key)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _download_allowed(allow_download: bool = False) -> bool:
+    return bool(allow_download) or _env_bool("LATTICEAI_ALLOW_MODEL_DOWNLOADS", default=False) or bool(AUTOLOAD_MODELS)
+
+
+def _download_block(provider: str, model_name: str) -> None:
+    raise HTTPException(
+        status_code=409,
+        detail={
+            "status": "unavailable",
+            "capability": "model_download",
+            "provider": provider,
+            "model": model_name,
+            "reason": (
+                "Model files are not present locally. Lattice AI does not start "
+                "outbound model downloads by default, and token/model presence "
+                "alone never authorizes network activity."
+            ),
+            "action": "Use the explicit pull/prepare flow with download consent, or set LATTICEAI_ALLOW_MODEL_DOWNLOADS=true.",
+        },
+    )
+
+
+def _engine_install_block(engine: str) -> None:
+    raise HTTPException(
+        status_code=409,
+        detail={
+            "status": "unavailable",
+            "capability": "engine_install",
+            "engine": engine,
+            "reason": (
+                "The requested local runtime is not installed. Lattice AI does not "
+                "run package-manager or installer commands from Model Load by default."
+            ),
+            "action": "Install the runtime explicitly from Library/System setup, or enable explicit download/install consent for this request.",
+        },
+    )
+
+
 def _missing_current_user(_request: Request) -> Optional[str]:
     return None
 
@@ -1307,6 +1352,7 @@ async def prepare_and_load_model(
     user_email: Optional[str] = None,
     adapter_path: Optional[str] = None,
     draft_model_id: Optional[str] = None,
+    allow_download: bool = False,
 ) -> Dict[str, object]:
     model_id = normalize_local_model_request(model_id, engine)
     if not model_id:
@@ -1329,11 +1375,15 @@ async def prepare_and_load_model(
     download_result: Optional[Dict[str, object]] = None
 
     if parsed_provider in local_engines:
+        if not engine_installed(parsed_provider) and not _download_allowed(allow_download):
+            _engine_install_block(parsed_provider)
         install_result = ensure_engine_ready(parsed_provider)
 
     if parsed_provider == "local_mlx":
         explicit_path = Path(parsed_model).expanduser()
         if not explicit_path.exists() and not hf_model_ready(parsed_model, "local_mlx"):
+            if not _download_allowed(allow_download):
+                _download_block(parsed_provider, parsed_model)
             download_result = download_hf_model(parsed_model, "local_mlx")
     elif parsed_provider == "ollama":
         ensure_ollama_server()
@@ -1341,6 +1391,8 @@ async def prepare_and_load_model(
         if not ollama:
             raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
         if parsed_model not in get_ollama_pulled_models():
+            if not _download_allowed(allow_download):
+                _download_block(parsed_provider, parsed_model)
             completed = subprocess.run(
                 [ollama, "pull", parsed_model],
                 capture_output=True,
@@ -1352,12 +1404,23 @@ async def prepare_and_load_model(
                 raise HTTPException(status_code=500, detail=completed.stderr[-2000:] or "Ollama 모델 다운로드 실패")
             download_result = {"provider": "ollama", "model": parsed_model, "returncode": completed.returncode}
     elif parsed_provider == "vllm":
+        if not hf_model_ready(parsed_model, "vllm") and not _download_allowed(allow_download):
+            _download_block(parsed_provider, parsed_model)
         ensure_vllm_server(parsed_model)
         download_result = {"provider": "vllm", "model": parsed_model, "server_ready": True}
     elif parsed_provider == "llamacpp":
+        if not hf_model_ready(parsed_model, "llamacpp") and not _download_allowed(allow_download):
+            _download_block(parsed_provider, parsed_model)
         ensure_llamacpp_server(parsed_model)
         download_result = {"provider": "llamacpp", "model": parsed_model, "server_ready": True}
     elif parsed_provider == "lmstudio":
+        downloaded = {
+            str(item.get("key") or "").strip()
+            for item in get_lmstudio_models()
+            if isinstance(item, dict)
+        }
+        if parsed_model not in downloaded and not _download_allowed(allow_download):
+            _download_block(parsed_provider, parsed_model)
         ensured = ensure_lmstudio_model(parsed_model)
         resolved_model = str(
             ensured.get("instance_id")
@@ -1399,7 +1462,7 @@ async def prepare_and_load_model(
         "installed_now": bool(install_result.get("installed_now")),
         "download": download_result,
         "resolution": resolution.to_dict(),
-        "downloaded": True,
+        "downloaded": bool(download_result and not (isinstance(download_result, dict) and download_result.get("cached"))),
         "loaded": True,
         "ready_to_chat": ready_to_chat,
         "compatibility_status": compat_status,
@@ -1416,6 +1479,7 @@ async def prepare_and_load_model_stream(
     request: Request,
     engine: Optional[str] = None,
     user_email: Optional[str] = None,
+    allow_download: bool = False,
 ) -> AsyncIterator[str]:
     model_id = normalize_local_model_request(model_id, engine)
     if not model_id:
@@ -1446,6 +1510,8 @@ async def prepare_and_load_model_stream(
                     percent=2,
                     indeterminate=True,
                 ))
+                if not engine_installed(parsed_provider) and not _download_allowed(allow_download):
+                    _engine_install_block(parsed_provider)
                 install_result = ensure_engine_ready(parsed_provider)
                 emit_progress(model_download_progress_payload(
                     "engine",
@@ -1466,6 +1532,8 @@ async def prepare_and_load_model_stream(
                         eta_seconds=0,
                     ))
                 elif not hf_model_ready(parsed_model, "local_mlx"):
+                    if not _download_allowed(allow_download):
+                        _download_block(parsed_provider, parsed_model)
                     download_result = download_hf_model(parsed_model, "local_mlx", progress_emit=emit_progress)
                 else:
                     download_result = {"model": parsed_model, "path": str(hf_model_dir(parsed_model)), "cached": True}
@@ -1484,6 +1552,8 @@ async def prepare_and_load_model_stream(
                 ))
                 ensure_ollama_server()
                 if parsed_model not in get_ollama_pulled_models():
+                    if not _download_allowed(allow_download):
+                        _download_block(parsed_provider, parsed_model)
                     download_result = pull_ollama_model_with_progress(parsed_model, progress_emit=emit_progress)
                 else:
                     download_result = {"provider": "ollama", "model": parsed_model, "cached": True}
@@ -1496,6 +1566,8 @@ async def prepare_and_load_model_stream(
                     ))
             elif parsed_provider == "vllm":
                 if not hf_model_ready(parsed_model, "vllm"):
+                    if not _download_allowed(allow_download):
+                        _download_block(parsed_provider, parsed_model)
                     download_result = download_hf_model(parsed_model, "vllm", progress_emit=emit_progress)
                 else:
                     download_result = {"provider": "vllm", "model": parsed_model, "cached": True}
@@ -1516,6 +1588,8 @@ async def prepare_and_load_model_stream(
                 download_result = {**(download_result or {}), "provider": "vllm", "model": parsed_model, "server_ready": True}
             elif parsed_provider == "llamacpp":
                 if not hf_model_ready(parsed_model, "llamacpp"):
+                    if not _download_allowed(allow_download):
+                        _download_block(parsed_provider, parsed_model)
                     download_result = download_hf_model(parsed_model, "llamacpp", progress_emit=emit_progress)
                 else:
                     download_result = {"provider": "llamacpp", "model": parsed_model, "cached": True}
@@ -1535,6 +1609,13 @@ async def prepare_and_load_model_stream(
                 ensure_llamacpp_server(parsed_model)
                 download_result = {**(download_result or {}), "provider": "llamacpp", "model": parsed_model, "server_ready": True}
             elif parsed_provider == "lmstudio":
+                downloaded = {
+                    str(item.get("key") or "").strip()
+                    for item in get_lmstudio_models()
+                    if isinstance(item, dict)
+                }
+                if parsed_model not in downloaded and not _download_allowed(allow_download):
+                    _download_block(parsed_provider, parsed_model)
                 emit_progress(model_download_progress_payload(
                     "download",
                     "LM Studio 모델을 확인하는 중입니다.",
@@ -1643,7 +1724,7 @@ async def prepare_and_load_model_stream(
         "installed_now": bool(isinstance(install_result, dict) and install_result.get("installed_now")),
         "download": download_result,
         "resolution": resolution_stream.to_dict(),
-        "downloaded": True,
+        "downloaded": bool(download_result and not (isinstance(download_result, dict) and download_result.get("cached"))),
         "loaded": True,
         "ready_to_chat": ready_to_chat,
         "compatibility_status": compat_status,

package/ltcai_cli.py

@@ -246,9 +246,15 @@ def main() -> None:
 
     os.chdir(app_dir)
 
-    # LATTICEAI_TUNNEL=true in .env acts like --tunnel flag
-    if not args.tunnel and os.getenv("LATTICEAI_TUNNEL", "").lower() in ("1", "true", "yes"):
-        args.tunnel = True
+    if not args.tunnel and os.getenv("LATTICEAI_TUNNEL", "").lower() in (
+        "1",
+        "true",
+        "yes",
+    ):
+        print(
+            "  LATTICEAI_TUNNEL is ignored during default local startup; "
+            "restart with --tunnel to expose this server."
+        )
 
     # --tunnel forces 0.0.0.0 so cloudflared can reach the server
     if args.tunnel and args.host == "127.0.0.1":
@@ -257,6 +263,11 @@ def main() -> None:
         os.environ.setdefault("LATTICEAI_CORS_ALLOW_NETWORK", "true")
         os.environ.setdefault("LATTICEAI_REQUIRE_AUTH", "true")
 
+    # Keep the app config in sync with CLI flags. ``Config.from_env`` is the
+    # source of truth for /mode, /health.features, SSO defaults, and routers.
+    os.environ["LATTICEAI_HOST"] = str(args.host)
+    os.environ["LATTICEAI_PORT"] = str(args.port)
+
     tunnel_url: str | None = None
     if args.tunnel:
         print()
@@ -269,9 +280,10 @@ def main() -> None:
 
     # Telegram startup notification (local start, tunnel handled separately inside _start_tunnel)
     if not args.tunnel:
+        _tg_enabled = os.getenv("LATTICEAI_ENABLE_TELEGRAM", "").strip().lower() in ("1", "true", "yes", "on")
         _tg_token = os.getenv("LATTICEAI_TELEGRAM_BOT_TOKEN", "")
         _tg_chat  = os.getenv("LATTICEAI_TELEGRAM_CHAT_ID", "")
-        if _tg_token and _tg_chat:
+        if _tg_enabled and _tg_token and _tg_chat:
             _local_msg = (
                 f"✅ Lattice AI 시작됨\n\n"
                 f"🏠 로컬: http://localhost:{args.port}"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ltcai",
-  "version": "4.2.0",
-  "description": "Lattice AI — local-first Digital Brain Platform (knowledge graph, durable memory, hybrid search, agents, signed brain exchange)",
+  "version": "4.3.1",
+  "description": "Lattice AI — local-first Digital Brain Platform (knowledge graph, durable memory, hybrid search, agents, portable encrypted brain archives)",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
     "type": "git",
@@ -41,8 +41,8 @@
     "desktop:tauri:check": "cd src-tauri && cargo check",
     "desktop:electron": "electron desktop/electron/main.cjs",
     "package:vsix": "node scripts/build_vsix.mjs",
-    "release:artifacts": "npm run build:assets && npm run build:python && npm pack && npm run package:vsix",
-    "release:validate": "node scripts/run_python.mjs scripts/validate_release_artifacts.py $npm_package_version --require-vsix --require-tgz",
+    "release:artifacts": "node scripts/clean_release_artifacts.mjs $npm_package_version && npm run build:assets && npm run build:python && npm pack && npm run package:vsix && npm run desktop:tauri:build",
+    "release:validate": "node scripts/run_python.mjs scripts/validate_release_artifacts.py $npm_package_version --require-vsix --require-tgz --require-dmg",
     "publish:npm": "npm pack && npm publish ltcai-$npm_package_version.tgz --access public",
     "publish:pypi": "npm run build:python && node scripts/run_python.mjs -m twine upload --skip-existing dist/ltcai-$npm_package_version.tar.gz dist/ltcai-$npm_package_version-py3-none-any.whl",
     "publish:vscode": "cd vscode-extension && npm run package:vsix && npm run publish:vscode",
@@ -68,6 +68,7 @@
   "files": [
     "bin/ltcai.js",
     "LICENSE",
+    "requirements.txt",
     "ltcai_cli.py",
     "auto_setup.py",
     "server.py",

package/requirements.txt

@@ -0,0 +1,17 @@
+fastapi>=0.110,<1
+uvicorn>=0.29,<1
+pydantic>=2.7,<3
+httpx>=0.27,<1
+pillow>=10,<13
+openai>=1.30,<3
+python-docx>=1.1,<2
+openpyxl>=3.1,<4
+python-pptx>=0.6.23,<2
+python-multipart>=0.0.9,<0.1
+keyring>=24,<26
+authlib>=1.3,<2
+cryptography>=42,<49
+pdfplumber>=0.11,<0.12
+pypdfium2>=4.30,<6
+watchdog>=4,<7
+psycopg[binary]>=3.2,<4