forgexa-cli 1.21.0__tar.gz → 1.21.2__tar.gz

{forgexa_cli-1.21.0 → forgexa_cli-1.21.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.21.0
+Version: 1.21.2
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT

{forgexa_cli-1.21.0 → forgexa_cli-1.21.2}/forgexa_cli/__init__.py

@@ -1,2 +1,2 @@
 """forgexa-cli — Forgexa command-line client."""
-__version__ = "1.21.0"
+__version__ = "1.21.2"

{forgexa_cli-1.21.0 → forgexa_cli-1.21.2}/forgexa_cli/daemon.py

@@ -47,7 +47,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Awaitable, Callable
 from urllib.parse import urlparse
-from uuid import UUID
+from uuid import UUID, uuid4
 
 # fcntl is Unix-only; on Windows we skip file locking
 try:
@@ -555,7 +555,7 @@ except (ImportError, ModuleNotFoundError):
 # DAEMON_VERSION is the protocol/logic version of the daemon code.
 # Kept in sync with pyproject.toml version via bump-version.sh.
 # CLIENT_TYPE identifies which packaging/distribution this daemon runs in.
-DAEMON_VERSION = "1.21.0"
+DAEMON_VERSION = "1.21.2"
 
 
 def _detect_client_type() -> str:
@@ -780,8 +780,19 @@ def _prepare_agent_command(command: list[str]) -> list[str]:
 
     suffix = Path(command[0]).suffix.lower()
     if suffix in {".cmd", ".bat"}:
+        comspec = os.environ.get("COMSPEC", "")
+        if comspec and Path(comspec).is_file():
+            command_processor = comspec
+        else:
+            system_root = os.environ.get("SystemRoot") or os.environ.get("WINDIR", "")
+            system_cmd = Path(system_root) / "System32" / "cmd.exe" if system_root else None
+            command_processor = (
+                str(system_cmd)
+                if system_cmd and system_cmd.is_file()
+                else shutil.which("cmd.exe") or comspec or "cmd.exe"
+            )
         return [
-            os.environ.get("COMSPEC", "cmd.exe"),
+            command_processor,
             "/d",
             "/s",
             "/c",
@@ -800,6 +811,46 @@ def _prepare_agent_command(command: list[str]) -> list[str]:
     return command
 
 
+def _agent_process_group_kwargs() -> dict[str, bool]:
+    """Isolate agent process groups where the platform supports POSIX sessions."""
+    # Windows cleanup uses taskkill /T, and starting cmd.exe with a new session
+    # differs from the command path proven during agent discovery.
+    return {"start_new_session": True} if sys.platform != "win32" else {}
+
+
+def _resolve_git_command() -> str | None:
+    """Return Git's executable, including common Windows installer locations."""
+    resolved = shutil.which("git")
+    if resolved or sys.platform != "win32":
+        return resolved
+
+    home = Path.home()
+    roots = [
+        os.environ.get("ProgramFiles", ""),
+        os.environ.get("ProgramW6432", ""),
+        os.environ.get("ProgramFiles(x86)", ""),
+        str(Path(os.environ.get("LOCALAPPDATA", home / "AppData" / "Local")) / "Programs"),
+    ]
+    git_dirs = [
+        Path(root) / "Git" / directory
+        for root in roots if root
+        for directory in ("cmd", "bin", "usr" / Path("bin"))
+    ]
+    existing_dirs = [directory for directory in git_dirs if directory.is_dir()]
+    if existing_dirs:
+        current = os.environ.get("PATH", "")
+        current_dirs = set(current.split(os.pathsep))
+        additions = [str(directory) for directory in existing_dirs if str(directory) not in current_dirs]
+        if additions:
+            os.environ["PATH"] = os.pathsep.join(additions) + os.pathsep + current
+        for directory in existing_dirs:
+            candidate = directory / "git.exe"
+            if candidate.is_file():
+                return str(candidate)
+
+    return shutil.which("git")
+
+
 @dataclass
 class TaskInfo:
     task_id: str
@@ -835,6 +886,8 @@ class TaskResult:
     #   "all_agents_rate_limited" — daemon tried every installed agent, all
     #       hit rate/quota limits.  Server must NOT retry on the same runtime.
     failure_code: str = ""
+    # Optional structured preflight result for project/runtime preflight failures.
+    preflight: dict | None = None
     artifacts: list[dict] = field(default_factory=list)
     observations: list[dict] = field(default_factory=list)
     metrics: dict = field(default_factory=dict)
@@ -1712,10 +1765,8 @@ class WorkspaceManager:
 
     def __init__(self, root: str):
         self.root = Path(root).expanduser()
-        self.root.mkdir(parents=True, exist_ok=True)
         # Project repos live under projects/ to avoid mixing with other daemon files
         self.projects_root = self.root / "projects"
-        self.projects_root.mkdir(parents=True, exist_ok=True)
         self._ssh_keys: dict[str, str] = {}  # project_key -> PEM key content
         self._http_auth: dict[str, dict[str, str]] = {}  # project_key -> provider/token/username
 
@@ -1725,8 +1776,22 @@ class WorkspaceManager:
         self._worktree_locks: dict[str, asyncio.Lock] = {}
         self._worktree_locks_mu: asyncio.Lock = asyncio.Lock()
 
+        self._dirs_ready = False
+
+    def _ensure_dirs(self) -> None:
+        """Lazy initialization of workspace directories.
+
+        Called before first use (prepare_workspace or preflight check).
+        If the root cannot be created (permissions, disk full), the OSError
+        propagates to the caller — the daemon itself does NOT crash at startup.
+        """
+        if self._dirs_ready:
+            return
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.projects_root.mkdir(parents=True, exist_ok=True)
         # One-time migration: move legacy project dirs from root/ to projects/
         self._migrate_legacy_project_dirs()
+        self._dirs_ready = True
 
     def set_ssh_key(self, project_key: str, ssh_private_key: str) -> None:
         """Register an SSH private key for a project."""
@@ -1992,12 +2057,13 @@ class WorkspaceManager:
         if last_exc is not None:
             raise last_exc
 
-    async def prepare_workspace(self, project: dict, task: TaskInfo) -> Path:
-        """Create or reuse a workspace for the given task.
+    def _configure_project_git_auth(self, project: dict) -> tuple[str, str, str]:
+        """Register SSH key and HTTPS token auth for a project.
 
-        All nodes in the same execution graph share one workspace directory
-        and git branch so that design→coding→testing→review can see each
-        other's output files.
+        Extracted from prepare_workspace() so that project-level preflight
+        (ls-remote) can register credentials before worktree creation.
+
+        Returns (project_key, repo_url, default_branch).
         """
         project_key = project.get("project_key", "default")
         repo_url = project.get("repo_url", "")
@@ -2016,6 +2082,105 @@ class WorkspaceManager:
         if git_api_token:
             self.set_http_auth(project_key, git_provider, git_api_token, git_username or None)
 
+        return project_key, repo_url, default_branch
+
+    async def check_remote_access(self, project: dict) -> dict | None:
+        """Project-level preflight: verify remote repo access via ls-remote.
+
+        Returns None on success, or a structured preflight result dict on failure:
+
+            {"scope": "project", "checks": [{"id": "...", "status": "fail",
+              "failure_class": "...", "detail": "...", "remediation": "..."}]}
+
+        For local-init projects (empty repo_url), returns None (skip — not an error).
+        """
+        project_key, repo_url, default_branch = self._configure_project_git_auth(project)
+
+        # Empty repo_url is a legal local-init mode — no remote to check.
+        if not repo_url:
+            return None
+
+        ref = f"refs/heads/{default_branch}"
+        try:
+            output = await self._git(
+                "ls-remote", repo_url, ref,
+                project_key=project_key,
+                timeout=30,
+            )
+            if not output.strip():
+                # `git ls-remote` exits 0 even when the ref pattern matches no
+                # refs at all -- a missing branch is NOT reported as a command
+                # failure. Without this check, a typo'd or deleted default
+                # branch would silently pass preflight and only surface later
+                # as a worktree checkout failure.
+                return {
+                    "scope": "project",
+                    "checks": [
+                        {
+                            "id": "git_remote_access",
+                            "status": "fail",
+                            "blocking": True,
+                            "failure_class": "default_branch_missing",
+                            "detail": f"No ref matching '{ref}' found on remote",
+                            "remediation": f"Verify the default branch '{default_branch}' exists on the remote repository",
+                        }
+                    ],
+                }
+            return None  # success
+        except Exception as exc:
+            err_lower = str(exc).lower()
+            # Classify into failure_class using error markers (not free-text parsing)
+            if self._is_retryable_git_transport_error(exc):
+                failure_class = "network_transient"
+                remediation = "Check network connectivity, DNS, or firewall rules"
+            elif any(m in err_lower for m in (
+                "permission denied", "authentication failed", "access denied",
+                "could not read from remote", "fatal: could not read",
+                "invalid credentials", "unauthorized",
+            )):
+                failure_class = "auth_error"
+                remediation = "Check SSH key, deploy key, or HTTPS token permissions for this repository"
+            elif any(m in err_lower for m in (
+                "repository not found", "not found", "does not exist",
+                "no such repository",
+            )):
+                failure_class = "not_found"
+                remediation = "Verify the repository URL is correct and accessible"
+            elif any(m in err_lower for m in (
+                "refs/heads/", "remote branch", "no refs", "failed to resolve",
+            )):
+                failure_class = "default_branch_missing"
+                remediation = f"Default branch '{default_branch}' does not exist on remote"
+            else:
+                failure_class = "network_transient"
+                remediation = "Check repository URL, credentials, and network connectivity"
+
+            # Sanitize: strip embedded credentials from detail
+            safe_detail = self._summarize_git_error(exc)
+            return {
+                "scope": "project",
+                "checks": [
+                    {
+                        "id": "git_remote_access",
+                        "status": "fail",
+                        "blocking": True,
+                        "failure_class": failure_class,
+                        "detail": safe_detail[:500],
+                        "remediation": remediation,
+                    }
+                ],
+            }
+
+    async def prepare_workspace(self, project: dict, task: TaskInfo) -> Path:
+        """Create or reuse a workspace for the given task.
+
+        All nodes in the same execution graph share one workspace directory
+        and git branch so that design→coding→testing→review can see each
+        other's output files.
+        """
+        self._ensure_dirs()
+        project_key, repo_url, default_branch = self._configure_project_git_auth(project)
+
         project_dir = self.projects_root / project_key
         project_dir.mkdir(parents=True, exist_ok=True)
 
@@ -3311,7 +3476,7 @@ class WorkspaceManager:
         env = None
         git_prefix_args: list[str] = []
         # Inject SSH key for commands that touch the remote
-        remote_commands = {"clone", "fetch", "pull", "push"}
+        remote_commands = {"clone", "fetch", "pull", "push", "ls-remote"}
         if project_key and args and args[0] in remote_commands:
             key_content = self._ssh_keys.get(project_key)
             if key_content:
@@ -3413,6 +3578,15 @@ class WorkspaceManager:
                 git_prefix_args = self._build_http_git_config_args(project_key)
                 if git_prefix_args:
                     env = {**(env or os.environ), "GIT_TERMINAL_PROMPT": "0"}
+            elif args[0] == "ls-remote" and len(args) >= 2:
+                # HTTPS auth for ls-remote preflight: URL is args[1].
+                repo_candidate = args[1]
+                if isinstance(repo_candidate, str):
+                    parsed = urlparse(repo_candidate)
+                    if parsed.scheme in ("http", "https"):
+                        git_prefix_args = self._build_http_git_config_args(project_key)
+                        if git_prefix_args:
+                            env = {**(env or os.environ), "GIT_TERMINAL_PROMPT": "0"}
 
         # Apply optional partial-clone filter for large-repo support.
         # Injecting here centralises the setting across all call sites: callers
@@ -3430,6 +3604,12 @@ class WorkspaceManager:
         # reject long paths on platforms where it is already enabled).
         # On Linux/macOS this is a no-op.
         longpath_args = ["-c", "core.longpaths=true"]
+        git_command = _resolve_git_command()
+        if not git_command:
+            raise RuntimeError(
+                "Git executable not found. Install Git for Windows and ensure "
+                "'C:\\Program Files\\Git\\cmd' is accessible to the Forgexa daemon."
+            )
 
         # start_new_session=True puts git in its own process group.
         # On timeout we send SIGKILL to the entire group, which includes
@@ -3438,13 +3618,13 @@ class WorkspaceManager:
         # Windows note: start_new_session creates a new console process group;
         # we use taskkill /T there instead of killpg.
         proc = await asyncio.create_subprocess_exec(
-            "git", *longpath_args, *git_prefix_args, *args,
+            git_command, *longpath_args, *git_prefix_args, *args,
             stdin=asyncio.subprocess.DEVNULL,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
             cwd=str(cwd) if cwd else None,
             env=env,
-            start_new_session=True,
+            **_agent_process_group_kwargs(),
         )
         try:
             stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
@@ -4502,7 +4682,7 @@ class ProcessManager:
                 cwd=str(cwd),
                 env=env,
                 limit=100 * 1024 * 1024,  # 100MB line buffer for large JSON output from long sessions
-                start_new_session=True,  # own process group → killpg on timeout kills all children
+                **_agent_process_group_kwargs(),
             )
             self.active_processes[task_id] = proc
             stdout, stderr, returncode = await self._stream_process(
@@ -4559,6 +4739,16 @@ class ProcessManager:
                     error=f"Claude exited with code {returncode}: {stderr[-500:]}",
                     metrics=metrics,
                 )
+        except FileNotFoundError as exc:
+            logger.exception("Claude executable was not found for task %s", task_id)
+            return TaskResult(
+                status="failed",
+                exit_code=-1,
+                stdout="",
+                stderr="",
+                error=f"Claude launch failed: executable not found: {cmd[0]!r} ({exc})",
+                failure_code="agent_launch_not_found",
+            )
         except asyncio.TimeoutError as exc:
             _kill_proc(self.active_processes.pop(task_id, None) or proc)
             _err = (
@@ -5237,7 +5427,7 @@ class ProcessManager:
                 cwd=str(cwd),
                 env=env,
                 limit=100 * 1024 * 1024,
-                start_new_session=True,
+                **_agent_process_group_kwargs(),
                 **_win_flags,
             )
             self.active_processes[task_id] = proc
@@ -5367,6 +5557,19 @@ class ProcessManager:
                     error=failure_error,
                     metrics=metrics,
                 )
+        except FileNotFoundError as exc:
+            logger.exception("Copilot executable was not found for task %s", task_id)
+            return TaskResult(
+                status="failed",
+                exit_code=-1,
+                stdout="",
+                stderr="",
+                error=(
+                    f"Copilot launch failed: executable not found: {cmd[0]!r}; "
+                    f"configured agent path: {agent.command!r} ({exc})"
+                ),
+                failure_code="agent_launch_not_found",
+            )
         except asyncio.TimeoutError as exc:
             _kill_proc(self.active_processes.pop(task_id, None) or proc)
             _err = (
@@ -5428,7 +5631,7 @@ class ProcessManager:
                 cwd=str(cwd),
                 env=env,
                 limit=100 * 1024 * 1024,  # 100MB line buffer for large agent output
-                start_new_session=True,  # own process group → killpg on timeout kills all children
+                **_agent_process_group_kwargs(),
             )
             self.active_processes[task_id] = proc
             stdin_bytes = stdin_input.encode() if stdin_input else None
@@ -5445,6 +5648,16 @@ class ProcessManager:
                 stderr=stderr[-10000:],
                 error="" if status == "success" else f"Exited with code {returncode}",
             )
+        except FileNotFoundError as exc:
+            logger.exception("Agent executable was not found for task %s", task_id)
+            return TaskResult(
+                status="failed",
+                exit_code=-1,
+                stdout="",
+                stderr="",
+                error=f"Agent launch failed: executable not found: {cmd[0]!r} ({exc})",
+                failure_code="agent_launch_not_found",
+            )
         except asyncio.TimeoutError as exc:
             _kill_proc(self.active_processes.pop(task_id, None) or proc)
             _err = (
@@ -6179,6 +6392,7 @@ class ProgressReporter:
             "stderr_tail": result.stderr[-5000:] if result.stderr else "",
             "error": result.error,
             "failure_code": result.failure_code,
+            "preflight": result.preflight,
             "files_changed": result.files_changed,
             "lines_added": result.lines_added,
             "lines_removed": result.lines_removed,
@@ -6208,6 +6422,285 @@ class ProgressReporter:
         logger.error("Exhausted %d attempts to report completion for task %s", max_attempts, task_id)
 
 
+# ── Runtime Preflight Monitor ──
+
+
+class RuntimePreflightMonitor:
+    """Daemon-level single-flight preflight monitor.
+
+    Runs environment checks (git, workspace, disk) periodically and produces
+    immutable snapshots consumed by heartbeats. Only one check cycle runs at
+    a time; if a cycle is still running when the next is due, the next is
+    skipped (never stacks subprocesses or threads).
+
+    The monitor is owned by ``RuntimeDaemon`` (not per-ServerConnection) so
+    that multi-server daemons only check once regardless of connection count.
+    """
+
+    def __init__(self, workspace_root: str, interval: int = 15):
+        self._workspace_root = workspace_root
+        self._interval = interval
+        self._session_id = str(uuid4())
+        self._generation = 0
+        self._snapshot: dict | None = None
+        self._in_flight = False
+        self._workspace_probe_in_flight = False
+        self._task: asyncio.Task | None = None
+
+    def get_snapshot(self) -> dict | None:
+        """Return the last completed preflight snapshot (for heartbeat)."""
+        return self._snapshot
+
+    async def start(self):
+        self._task = asyncio.create_task(self._loop())
+
+    async def stop(self):
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _loop(self):
+        # First check immediately so the daemon reports a real status ASAP.
+        await self._run_one_cycle()
+        while True:
+            await asyncio.sleep(self._interval)
+            await self._run_one_cycle()
+
+    async def _run_one_cycle(self):
+        if self._in_flight:
+            return
+        self._in_flight = True
+        try:
+            checks = await self._run_checks()
+            self._generation += 1
+            blocked = any(
+                c.get("status") == "fail" and c.get("blocking")
+                for c in checks
+            )
+            self._snapshot = {
+                "status": "blocked" if blocked else "ready",
+                "daemon_session_id": self._session_id,
+                "generation": self._generation,
+                "checked_at": datetime.now(timezone.utc).isoformat(),
+                "checks": checks,
+            }
+        except Exception as e:
+            logger.warning("Preflight check cycle failed: %s", e)
+        finally:
+            self._in_flight = False
+
+    async def _run_checks(self) -> list[dict]:
+        return [
+            await self._check_git_executable(),
+            await self._check_workspace_root(),
+            await self._check_workspace_disk(),
+        ]
+
+    @staticmethod
+    async def _run_command_timeout(cmd: list[str], timeout: float = 5) -> str | None:
+        """Run a command with a deadline. Returns stdout on success, None on timeout/error.
+
+        On timeout, kills the entire process tree (taskkill /T on Windows,
+        process group SIGKILL on POSIX) and waits for reaping before returning.
+        """
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                **_agent_process_group_kwargs(),
+            )
+        except Exception:
+            return None
+        try:
+            stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+            if proc.returncode == 0:
+                return stdout.decode("utf-8", errors="replace").strip()
+            return None
+        except asyncio.TimeoutError:
+            RuntimePreflightMonitor._kill_process_tree(proc)
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=3)
+            except Exception:
+                pass
+            return None
+
+    @staticmethod
+    def _kill_process_tree(proc):
+        """Best-effort kill of the entire process subtree."""
+        try:
+            if sys.platform == "win32":
+                # Must be a BLOCKING call here: this is a plain (non-async)
+                # staticmethod, so asyncio.create_subprocess_exec(...) would
+                # return an unawaited coroutine that never actually runs --
+                # taskkill would silently never execute, leaking the hung
+                # process. Match the existing synchronous pattern already used
+                # by _kill_proc() and WorkspaceManager._git()'s timeout path.
+                import subprocess as _subprocess
+                _subprocess.run(
+                    ["taskkill", "/T", "/F", "/PID", str(proc.pid)],
+                    capture_output=True,
+                )
+            else:
+                import signal
+                try:
+                    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+        except Exception:
+            pass
+
+    async def _check_git_executable(self) -> dict:
+        """Check that git can be resolved and executed."""
+        try:
+            git_cmd = _resolve_git_command()
+            if not git_cmd:
+                return {
+                    "id": "git_executable",
+                    "status": "fail",
+                    "blocking": True,
+                    "failure_class": "command_not_found",
+                    "detail": "Git executable not found in PATH or standard locations",
+                    "remediation": "Install Git for Windows or add Git cmd directory to daemon PATH",
+                }
+            version = await self._run_command_timeout([git_cmd, "--version"], timeout=5)
+            if version is None:
+                return {
+                    "id": "git_executable",
+                    "status": "unknown",
+                    "blocking": True,
+                    "failure_class": "command_timeout",
+                    "detail": f"git --version timed out or failed at {git_cmd}",
+                    "remediation": "Check for filesystem, antivirus, or network-disk stalls",
+                }
+            return {
+                "id": "git_executable",
+                "status": "pass",
+                "blocking": True,
+                "failure_class": "",
+                "detail": f"{version} at {git_cmd}",
+                "remediation": "",
+            }
+        except Exception as e:
+            return {
+                "id": "git_executable",
+                "status": "fail",
+                "blocking": True,
+                "failure_class": "command_not_found",
+                "detail": f"Git check error: {type(e).__name__}",
+                "remediation": "Install Git or check daemon PATH",
+            }
+
+    async def _check_workspace_root(self) -> dict:
+        """Check that workspace root can be created and is writable.
+
+        The actual filesystem probe is blocking I/O (mkdir/open/write/unlink).
+        It must never run directly on the event loop: a hung network drive or
+        antivirus lock could otherwise freeze heartbeats and task polling for
+        this entire daemon. It runs in a worker thread with a bounded deadline;
+        a single-flight guard prevents queuing a new probe on top of one whose
+        thread is still stuck (threads cannot be forcibly cancelled).
+        """
+        if self._workspace_probe_in_flight:
+            return {
+                "id": "workspace_root",
+                "status": "unknown",
+                "blocking": True,
+                "failure_class": "command_timeout",
+                "detail": "Previous workspace probe has not returned yet",
+                "remediation": "Check for a hung network drive, antivirus lock, or slow disk",
+            }
+
+        root = Path(self._workspace_root)
+        probe_dir = root / ".preflight"
+        probe_file = probe_dir / f"probe_{os.getpid()}.tmp"
+
+        def _do_probe() -> None:
+            try:
+                root.mkdir(parents=True, exist_ok=True)
+                probe_dir.mkdir(parents=True, exist_ok=True)
+                fd = os.open(str(probe_file), os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+                try:
+                    os.write(fd, b"preflight-ok")
+                finally:
+                    os.close(fd)
+                os.unlink(str(probe_file))
+            finally:
+                self._workspace_probe_in_flight = False
+
+        self._workspace_probe_in_flight = True
+        try:
+            await asyncio.wait_for(asyncio.to_thread(_do_probe), timeout=5)
+            return {
+                "id": "workspace_root",
+                "status": "pass",
+                "blocking": True,
+                "failure_class": "",
+                "detail": str(root),
+                "remediation": "",
+            }
+        except asyncio.TimeoutError:
+            # Intentionally leave _workspace_probe_in_flight = True here; the
+            # worker thread's own finally block clears it whenever the OS call
+            # eventually returns. A timeout is not proof the filesystem is
+            # broken, so this must not be reported as a hard block.
+            return {
+                "id": "workspace_root",
+                "status": "unknown",
+                "blocking": True,
+                "failure_class": "command_timeout",
+                "detail": f"Workspace probe at {root} did not complete within 5s",
+                "remediation": "Check for a hung network drive, antivirus lock, or slow disk",
+            }
+        except OSError as e:
+            return {
+                "id": "workspace_root",
+                "status": "fail",
+                "blocking": True,
+                "failure_class": "permission_denied",
+                "detail": f"Cannot create/write workspace at {root}: {type(e).__name__}",
+                "remediation": "Check directory permissions, disk status, or security software",
+            }
+
+    async def _check_workspace_disk(self) -> dict:
+        """Check available disk space at workspace root (non-blocking warning)."""
+        try:
+            import psutil
+            usage = psutil.disk_usage(str(Path(self._workspace_root)))
+            free_gb = usage.free / (1024 ** 3)
+            threshold_gb = 5
+            if free_gb < threshold_gb:
+                return {
+                    "id": "workspace_disk",
+                    "status": "fail",
+                    "blocking": False,
+                    "failure_class": "disk_full",
+                    "detail": f"{free_gb:.1f} GB free at {self._workspace_root}",
+                    "remediation": f"Free at least {threshold_gb} GB for workspace operations",
+                }
+            return {
+                "id": "workspace_disk",
+                "status": "pass",
+                "blocking": False,
+                "failure_class": "",
+                "detail": f"{free_gb:.1f} GB free",
+                "remediation": "",
+            }
+        except Exception:
+            return {
+                "id": "workspace_disk",
+                "status": "unknown",
+                "blocking": False,
+                "failure_class": "",
+                "detail": "disk usage check unavailable",
+                "remediation": "",
+            }
+
+
 # ── Heartbeat Service ──
 
 
@@ -6221,6 +6714,7 @@ class HeartbeatService:
         runtime_id: str,
         daemon_id: str,
         interval: int = 15,
+        preflight_snapshot_provider: Callable[[], dict | None] | None = None,
     ):
         self.client = client
         self.server_url = server_url.rstrip("/")
@@ -6230,6 +6724,7 @@ class HeartbeatService:
         self._task: asyncio.Task | None = None
         self._active_tasks = 0
         self._agents: list[dict] = []
+        self._preflight_snapshot_provider = preflight_snapshot_provider or (lambda: None)
         self._on_success = lambda: None  # Callbacks set by ServerConnection
         self._on_auth_failure = lambda: None
 
@@ -6261,6 +6756,7 @@ class HeartbeatService:
                         "os_info": get_os_info(),
                         "daemon_version": DAEMON_VERSION,
                         "client_type": _CLIENT_TYPE,
+                        "execution_preflight": self._preflight_snapshot_provider(),
                     },
                     timeout=10,
                 )
@@ -6665,6 +7161,7 @@ class ServerConnection:
         heartbeat_interval: int,
         poll_interval: int,
         agents: list[DiscoveredAgent],
+        preflight_snapshot_provider: Callable[[], dict | None] | None = None,
     ):
         """Initialize heartbeat, poller, and reporter services."""
         self._agents = agents
@@ -6691,6 +7188,7 @@ class ServerConnection:
         self.heartbeat = HeartbeatService(
             self.client, self.server_url, self.runtime_id, self.daemon_id,
             heartbeat_interval,
+            preflight_snapshot_provider=preflight_snapshot_provider,
         )
         self.heartbeat._on_success = _on_auth_success
         self.heartbeat._on_auth_failure = _on_auth_failure
@@ -6930,6 +7428,12 @@ class RuntimeDaemon:
         self.process_manager = ProcessManager()
         self._lock_file = None  # File lock to prevent multiple daemon instances
 
+        # Daemon-level preflight monitor (shared across all ServerConnections).
+        # Single-flight: only one check cycle at a time regardless of server count.
+        self.preflight_monitor = RuntimePreflightMonitor(
+            self.workspaces_root, interval=self.heartbeat_interval,
+        )
+
     @staticmethod
     def _project_execution_key(project: dict | None, task_hint: str) -> str:
         project_info = project or {}
@@ -7296,6 +7800,10 @@ class RuntimeDaemon:
             logger.info("Discovered %d agent(s): %s", len(self.agents),
                        ", ".join(a.agent_id for a in self.agents))
 
+        # 1b. Start preflight monitor (runs first check immediately so the
+        # initial heartbeat already carries a real status snapshot).
+        await self.preflight_monitor.start()
+
         # 2. Register with all servers
         # 2. Register with all servers (with retry on transient failures)
         max_registration_attempts = 5
@@ -7316,7 +7824,10 @@ class RuntimeDaemon:
                 try:
                     await conn.register(self.agents, self.max_concurrent)
                     self.api_token = conn.api_token
-                    conn.start_services(self.heartbeat_interval, self.poll_interval, self.agents)
+                    conn.start_services(
+                        self.heartbeat_interval, self.poll_interval, self.agents,
+                        preflight_snapshot_provider=self.preflight_monitor.get_snapshot,
+                    )
                     await conn.start_heartbeat()
                     self.connections.append(conn)
                     logger.info("[%s] Connected and ready", conn.label)
@@ -7610,6 +8121,24 @@ class RuntimeDaemon:
             # Track which agents we've already tried (for rate-limit fallback)
             tried_agents: set[str] = set()
 
+            # 1b. Project-level preflight: verify remote repo access before
+            # worktree creation.  This catches auth errors, wrong default branch,
+            # and network issues BEFORE spending time on clone/checkout.
+            project_preflight = await self.workspace_manager.check_remote_access(
+                task.project,
+            )
+            if project_preflight:
+                _pf_checks = project_preflight.get("checks", [])
+                _pf_detail = _pf_checks[0].get("detail", "Project preflight failed") if _pf_checks else "Project preflight failed"
+                logger.warning("Project preflight failed for task %s: %s", task.task_id, _pf_detail)
+                await reporter.report_complete(task.task_id, TaskResult(
+                    status="failed", exit_code=-1, stdout="", stderr="",
+                    error=_pf_detail,
+                    failure_code="project_preflight_failed",
+                    preflight=project_preflight,
+                ))
+                return
+
             # 2. Prepare workspace
             await reporter.report_progress(task.task_id, 5, "preparing_workspace")
             workspace_path = await self.workspace_manager.prepare_workspace(
@@ -11300,6 +11829,9 @@ class RuntimeDaemon:
             task.cancel()
             await self.process_manager.cancel(task_id)
 
+        # Stop preflight monitor
+        await self.preflight_monitor.stop()
+
         # Stop all server connections (heartbeat + unregister)
         for conn in self.connections:
             await conn.stop()

{forgexa_cli-1.21.0 → forgexa_cli-1.21.2}/forgexa_cli/main.py

@@ -1683,6 +1683,65 @@ def _print_check_report(results: list[dict], quick: bool) -> None:
         print("Gemini CLI, Kimi Code, or GitHub Copilot CLI), then re-run: forgexa check")
 
 
+def _run_environment_checks(narrate: bool) -> bool:
+    """Run environment checks (git, workspace, disk) using the daemon's check logic.
+
+    Returns True if any blocking check failed.
+    Prints a flutter-doctor-style listing in table mode.
+    """
+    import asyncio
+    from forgexa_cli.daemon import RuntimePreflightMonitor, settings
+
+    workspace_root = settings.get_daemon_workspaces_root()
+
+    if narrate:
+        print("Environment Checks (this CLI process scope):")
+        print(f"  Workspace root: {workspace_root}")
+        print()
+
+    monitor = RuntimePreflightMonitor(workspace_root, interval=999)
+    try:
+        checks = asyncio.run(monitor._run_checks())
+    except Exception as exc:
+        if narrate:
+            print(f"  [ERROR] Environment check failed: {exc}")
+        return True
+
+    blocking_failed = False
+    for check in checks:
+        status = check.get("status", "unknown")
+        check_id = check.get("id", "?")
+        detail = check.get("detail", "")
+        blocking = check.get("blocking", False)
+        remediation = check.get("remediation", "")
+
+        if status == "pass":
+            icon = "[OK]"
+        elif status == "fail":
+            icon = "[FAIL]" if blocking else "[WARN]"
+            if blocking:
+                blocking_failed = True
+        elif status == "unknown":
+            icon = "[?]"
+        else:
+            icon = f"[{status.upper()}]"
+
+        if narrate:
+            print(f"  {icon} {check_id}: {detail}")
+            if remediation:
+                print(f"        -> {remediation}")
+            print()
+
+    if narrate:
+        if blocking_failed:
+            print("One or more blocking checks failed. Fix them before running tasks.")
+        else:
+            print("All environment checks passed.")
+        print()
+
+    return blocking_failed
+
+
 def cmd_check(args: argparse.Namespace) -> None:
     """Verify locally-installed AI agent CLIs are genuinely usable for platform tasks.
 
@@ -1698,8 +1757,24 @@ def cmd_check(args: argparse.Namespace) -> None:
 
     only_agent = getattr(args, "agent", None)
     quick = bool(getattr(args, "quick", False))
+    environment_only = bool(getattr(args, "environment", False))
     timeout = getattr(args, "timeout", None) or 90
 
+    narrate = _fmt() == "table"
+    env_failed = False
+
+    # ── Environment checks (shared with daemon's RuntimePreflightMonitor) ──
+    # Run when --environment or --quick is set. These are free (no API calls,
+    # no network, no LLM tokens) and reuse the exact same check logic the
+    # daemon uses for its periodic preflight.
+    if environment_only or quick:
+        env_failed = _run_environment_checks(narrate)
+        if environment_only:
+            # --environment: only env checks, then exit
+            if env_failed:
+                sys.exit(1)
+            return
+
     known_ids = list(AgentDiscovery.AGENT_REGISTRY.keys())
     if only_agent:
         if only_agent not in known_ids:
@@ -1709,7 +1784,6 @@ def cmd_check(args: argparse.Namespace) -> None:
     else:
         agent_ids = known_ids
 
-    narrate = _fmt() == "table"
     if narrate:
         print("Scanning for installed agent CLIs...")
         if not quick:
@@ -1725,7 +1799,7 @@ def cmd_check(args: argparse.Namespace) -> None:
 
     _print_check_report(results, quick=quick)
 
-    if not any(r["available"] for r in results):
+    if env_failed or not any(r["available"] for r in results):
         sys.exit(1)
 
 
@@ -2203,7 +2277,11 @@ def main() -> None:
     check_p.add_argument("--agent", default=None, help="Check only this agent (e.g. claude, codex, kimi)")
     check_p.add_argument(
         "--quick", action="store_true",
-        help="Discovery only — skip the live task execution test (no API calls)",
+        help="Discovery + environment checks — skip the live task execution test (no API calls)",
+    )
+    check_p.add_argument(
+        "--environment", action="store_true",
+        help="Environment checks only (git, workspace, disk) — skip agent discovery and live calls",
     )
     check_p.add_argument(
         "--timeout", type=int, default=90, metavar="SECONDS",

{forgexa_cli-1.21.0 → forgexa_cli-1.21.2}/forgexa_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.21.0
+Version: 1.21.2
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT

{forgexa_cli-1.21.0 → forgexa_cli-1.21.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forgexa-cli"
-version = "1.21.0"
+version = "1.21.2"
 description = "Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform"
 requires-python = ">=3.9"
 license = "MIT"