forgexa-cli 1.21.7__tar.gz → 1.22.0__tar.gz

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.21.7
+Version: 1.22.0
 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
@@ -137,6 +137,26 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### One-Shot Upgrade Script (recommended for production runtimes)
+
+`forgexa upgrade` alone only auto-restarts the daemon if it was already running in background mode *right before* the upgrade started — if it had already stopped for any other reason (crash, manual stop, first-time setup), you're left to restart it yourself. [`cli/scripts/upgrade.sh`](scripts/upgrade.sh) (macOS/Linux) and [`cli/scripts/upgrade.ps1`](scripts/upgrade.ps1) (Windows) wrap the full, correct sequence explicitly so the daemon is deterministically stopped, upgraded, and started again in the background every time, regardless of its state going in:
+
+```bash
+# macOS / Linux
+./cli/scripts/upgrade.sh
+./cli/scripts/upgrade.sh --target-version 1.21.7
+./cli/scripts/upgrade.sh --server-url https://api.forgexa.net --login
+```
+
+```powershell
+# Windows
+.\cli\scripts\upgrade.ps1
+.\cli\scripts\upgrade.ps1 -TargetVersion 1.21.7
+.\cli\scripts\upgrade.ps1 -ServerUrl https://api.forgexa.net -Login
+```
+
+Steps: `daemon stop` (no-op if not running) → `upgrade` → `daemon start -d` → optional `login` → `daemon status`. Login is skipped by default (the previously saved session is reused) unless you pass `--email`/`--password` (`-Email`/`-Password`), set `FORGEXA_LOGIN_EMAIL`/`FORGEXA_LOGIN_PASSWORD`, or pass `--login`/`-Login` to be prompted interactively. Run with `--help`/`Get-Help .\upgrade.ps1` for all options.
+
 ### Automatic Background Upgrade
 
 By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/README.md

@@ -105,6 +105,26 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### One-Shot Upgrade Script (recommended for production runtimes)
+
+`forgexa upgrade` alone only auto-restarts the daemon if it was already running in background mode *right before* the upgrade started — if it had already stopped for any other reason (crash, manual stop, first-time setup), you're left to restart it yourself. [`cli/scripts/upgrade.sh`](scripts/upgrade.sh) (macOS/Linux) and [`cli/scripts/upgrade.ps1`](scripts/upgrade.ps1) (Windows) wrap the full, correct sequence explicitly so the daemon is deterministically stopped, upgraded, and started again in the background every time, regardless of its state going in:
+
+```bash
+# macOS / Linux
+./cli/scripts/upgrade.sh
+./cli/scripts/upgrade.sh --target-version 1.21.7
+./cli/scripts/upgrade.sh --server-url https://api.forgexa.net --login
+```
+
+```powershell
+# Windows
+.\cli\scripts\upgrade.ps1
+.\cli\scripts\upgrade.ps1 -TargetVersion 1.21.7
+.\cli\scripts\upgrade.ps1 -ServerUrl https://api.forgexa.net -Login
+```
+
+Steps: `daemon stop` (no-op if not running) → `upgrade` → `daemon start -d` → optional `login` → `daemon status`. Login is skipped by default (the previously saved session is reused) unless you pass `--email`/`--password` (`-Email`/`-Password`), set `FORGEXA_LOGIN_EMAIL`/`FORGEXA_LOGIN_PASSWORD`, or pass `--login`/`-Login` to be prompted interactively. Run with `--help`/`Get-Help .\upgrade.ps1` for all options.
+
 ### Automatic Background Upgrade
 
 By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/forgexa_cli/__init__.py

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

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/forgexa_cli/daemon.py

@@ -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.7"
+DAEMON_VERSION = "1.22.0"
 
 
 def _detect_client_type() -> str:
@@ -990,6 +990,12 @@ class TaskInfo:
     requirement_key: str | None = None
     graph_type: str = "execution"
     analysis_branch: str | None = None
+    # Explicit workspace baseline resolved server-side (SI-887).  When set,
+    # these override the legacy requirement_key-based branch derivation:
+    #   "requirement_branch" -> checkout workspace_branch, fail closed
+    #   "default_branch"     -> detached HEAD at origin/workspace_branch, never push
+    workspace_source_mode: str | None = None
+    workspace_branch: str | None = None
 
 
 @dataclass
@@ -2375,7 +2381,22 @@ class WorkspaceManager:
 
         # Use human-readable branch name feature/{requirement_key}
         # when requirement_key is available; fallback to feature/{workspace_key}
-        if task.requirement_key:
+        #
+        # Explicit server-resolved baseline (SI-887) takes precedence over the
+        # legacy requirement_key derivation:
+        #   - "requirement_branch": checkout the given branch, fail closed.
+        #   - "default_branch": detached HEAD at origin/<branch> (QA read-only
+        #     context) — never probe feature/{key}, never push.
+        ws_source_mode = task.workspace_source_mode
+        detach_head = ws_source_mode == "default_branch"
+        if ws_source_mode == "requirement_branch":
+            branch_name = task.workspace_branch or (
+                f"feature/{task.requirement_key}" if task.requirement_key
+                else f"feature/{workspace_key}"
+            )
+        elif detach_head:
+            branch_name = task.workspace_branch or default_branch
+        elif task.requirement_key:
             branch_name = f"feature/{task.requirement_key}"
         else:
             branch_name = f"feature/{workspace_key}"
@@ -2408,16 +2429,25 @@ class WorkspaceManager:
             # reflects the branch from a *previous* analysis run (e.g. a prior Copilot
             # analysis) which may have been deleted as part of the fresh restart.
             # Only refine/continuation tasks require the branch to already exist.
-            expect_branch = (not is_fresh_start) and (
-                bool(task.analysis_branch) or (
-                    bool(task.requirement_key) and task.node_type != "analysis"
+            if ws_source_mode == "requirement_branch":
+                # Server-resolved requirement baseline: the branch must exist.
+                expect_branch = True
+            elif detach_head:
+                # Server-resolved default-branch baseline: read-only QA context,
+                # never fail closed on the delivery branch protection.
+                expect_branch = False
+            else:
+                expect_branch = (not is_fresh_start) and (
+                    bool(task.analysis_branch) or (
+                        bool(task.requirement_key) and task.node_type != "analysis"
+                    )
                 )
-            )
             ws_path = await self._create_worktree(
                 project_dir, repo_url, default_branch, workspace_key, branch_name,
                 fresh_start=is_fresh_start,
                 project_key=project_key,
                 expect_branch=expect_branch,
+                detach_head=detach_head,
             )
             # After workspace creation, perform a final branch-specific fetch + reset
             # to ensure the working tree is at the absolute latest remote state.
@@ -2427,7 +2457,9 @@ class WorkspaceManager:
             #      may have pushed commits while this runtime's agent was executing.
             #      A final sync here keeps the workspace current so the agent works
             #      on the latest codebase and avoids non-fast-forward push failures.
-            if not is_fresh_start:
+            # Skipped for detach_head (default-branch QA baseline): the detached
+            # worktree path already fetched and pinned HEAD to origin/<branch>.
+            if not is_fresh_start and not detach_head:
                 sync_success = False
                 sync_error = ""
                 try:
@@ -2893,10 +2925,163 @@ class WorkspaceManager:
                 self._worktree_locks[key] = asyncio.Lock()
             return self._worktree_locks[key]
 
+    async def _refresh_or_invalidate_detached_worktree(
+        self, main_repo: Path, ws_path: Path, branch_name: str, *, project_key: str,
+    ) -> bool:
+        """Refresh an existing healthy detached-mode worktree onto origin/<branch_name>.
+
+        Returns True when the worktree was successfully refreshed/re-pinned and
+        the caller should reuse it as-is. Returns False when it was removed and
+        the caller must fall through to full recreation.
+
+        SI-887 review fix: a worktree still checked out on a real local branch
+        (not yet detached) is a leftover requirement_branch-mode checkout from
+        before a baseline switch. That content must never be silently reused
+        just because the refresh fetch below happens to fail — doing so would
+        run the job against the wrong baseline entirely, not merely stale
+        content. Only an already-detached worktree (same-mode refresh) may
+        tolerate a fetch failure, matching the daemon's existing tolerance of
+        transient fetch errors elsewhere when there is no baseline-identity
+        risk.
+        """
+        stale_branch_checkout = False
+        try:
+            await self._git("symbolic-ref", "-q", "HEAD", cwd=ws_path)
+            stale_branch_checkout = True
+        except RuntimeError:
+            pass  # already detached
+
+        try:
+            await self._git(
+                "fetch", "origin",
+                f"{branch_name}:refs/remotes/origin/{branch_name}",
+                cwd=ws_path, timeout=settings.GIT_FETCH_TIMEOUT,
+                project_key=project_key,
+            )
+        except RuntimeError as exc:
+            if not stale_branch_checkout:
+                logger.warning(
+                    "fetch origin/%s failed for QA workspace %s: %s — reusing current checkout",
+                    branch_name, ws_path, exc,
+                )
+                return True
+            logger.warning(
+                "fetch origin/%s failed for QA workspace %s while switching off a "
+                "requirement-branch baseline: %s — discarding the stale checkout "
+                "instead of running this job against the wrong baseline",
+                branch_name, ws_path, exc,
+            )
+            await self._remove_broken_worktree(main_repo, ws_path, ws_path.name)
+            return False
+
+        try:
+            await self._git(
+                "checkout", "-f", "--detach", f"origin/{branch_name}",
+                cwd=ws_path,
+            )
+        except RuntimeError as exc:
+            logger.warning(
+                "Failed to detach QA workspace %s onto origin/%s: %s — recreating",
+                ws_path, branch_name, exc,
+            )
+            await self._remove_broken_worktree(main_repo, ws_path, ws_path.name)
+            return False
+        return True
+
+    async def _create_detached_worktree(
+        self, repo_url: str, main_repo: Path, ws_path: Path, branch_name: str,
+        *, default_branch: str, project_key: str = "default",
+    ) -> Path:
+        """Create or refresh a read-only worktree pinned to origin/<branch_name>.
+
+        Used for server-resolved default-branch QA baselines (SI-887): the
+        worktree is checked out at a DETACHED HEAD so it never collides with
+        the default branch held by _main, never creates/tracks a local branch,
+        and is never pushed.  AI job results flow back via the API only.
+        """
+        if ws_path.exists():
+            if not await self._is_healthy_worktree(ws_path, main_repo=main_repo):
+                logger.warning("Broken worktree detected at %s — removing and recreating", ws_path)
+                await self._remove_broken_worktree(main_repo, ws_path, ws_path.name)
+            else:
+                # Reuse: refresh origin/<branch_name> and re-pin HEAD onto it (or
+                # discard and fall through to full recreation below) — see
+                # _refresh_or_invalidate_detached_worktree for the baseline-switch
+                # safety rationale.
+                if await self._refresh_or_invalidate_detached_worktree(
+                    main_repo, ws_path, branch_name, project_key=project_key,
+                ):
+                    return ws_path
+
+        # Ensure _main exists (single-branch clone of the default branch).
+        if not main_repo.exists():
+            await self._clone_repo(
+                repo_url, main_repo, branch=default_branch, project_key=project_key,
+            )
+        else:
+            # Same interrupted-clone guard as the feature-branch path: without a
+            # valid HEAD / readable tree, worktree add would always fail.
+            try:
+                await self._git("rev-parse", "HEAD", cwd=main_repo)
+                await self._git("rev-parse", "HEAD^{tree}", cwd=main_repo)
+            except RuntimeError:
+                logger.warning(
+                    "_main repo at %s has no valid HEAD (likely interrupted initial clone) "
+                    "— deleting and re-cloning from scratch",
+                    main_repo,
+                )
+                await self._safe_rmtree_main(main_repo)
+                if main_repo.exists():
+                    raise RuntimeError(
+                        f"Cannot re-clone: {main_repo} could not be fully removed "
+                        "(files may be locked by another process). "
+                        "Please stop the daemon, manually delete it, then restart."
+                    )
+                await self._clone_repo(
+                    repo_url, main_repo, branch=default_branch, project_key=project_key,
+                )
+
+        # Refresh origin/<branch_name>.  _main is a single-branch clone of the
+        # default branch and branch_name is the server-resolved baseline
+        # (normally that same default branch); fetch the explicit refspec so
+        # the pin below always has a fresh ref.
+        try:
+            await self._git(
+                "fetch", "origin",
+                f"{branch_name}:refs/remotes/origin/{branch_name}",
+                cwd=main_repo, timeout=settings.GIT_FETCH_TIMEOUT,
+                project_key=project_key,
+            )
+        except RuntimeError as exc:
+            raise RuntimeError(
+                f"Failed to fetch QA baseline branch '{branch_name}' from remote: {exc}"
+            ) from exc
+
+        try:
+            await self._git(
+                "worktree", "add", "--detach", str(ws_path), f"origin/{branch_name}",
+                cwd=main_repo,
+            )
+        except RuntimeError:
+            # A stale worktree registration may linger after a manual delete.
+            await self._git("worktree", "prune", cwd=main_repo)
+            try:
+                await self._git(
+                    "worktree", "add", "--detach", str(ws_path), f"origin/{branch_name}",
+                    cwd=main_repo,
+                )
+            except RuntimeError as exc:
+                self._safe_rmtree(ws_path)
+                raise RuntimeError(
+                    f"Failed to create detached QA workspace at origin/{branch_name}: {exc}"
+                ) from exc
+        return ws_path
+
     async def _create_worktree(
         self, project_dir: Path, repo_url: str, default_branch: str,
         workspace_key: str, branch_name: str, *, fresh_start: bool = False,
         project_key: str = "default", expect_branch: bool = False,
+        detach_head: bool = False,
     ) -> Path:
         # Serialize all _create_worktree calls for the same project to prevent
         # concurrent tasks from racing on _main (shutil.rmtree / git clone / worktree add).
@@ -2908,16 +3093,27 @@ class WorkspaceManager:
                 fresh_start=fresh_start,
                 project_key=project_key,
                 expect_branch=expect_branch,
+                detach_head=detach_head,
             )
 
     async def _create_worktree_impl(
         self, project_dir: Path, repo_url: str, default_branch: str,
         workspace_key: str, branch_name: str, *, fresh_start: bool = False,
         project_key: str = "default", expect_branch: bool = False,
+        detach_head: bool = False,
     ) -> Path:
         main_repo = project_dir / "_main"
         ws_path = project_dir / workspace_key
 
+        if detach_head:
+            # Server-resolved default-branch baseline (SI-887 QA context):
+            # dedicated path that never touches feature/* refs and pins the
+            # worktree to a detached HEAD at origin/<branch_name>.
+            return await self._create_detached_worktree(
+                repo_url, main_repo, ws_path, branch_name,
+                default_branch=default_branch, project_key=project_key,
+            )
+
         if ws_path.exists():
             # Validate that this worktree is healthy (its .git file points to a
             # valid main repo).  Worktrees break when directories are moved.
@@ -9540,6 +9736,13 @@ class RuntimeDaemon:
         user_prompt = aj.get("user_prompt", "")
         input_ctx = aj.get("input_context", {})
         ai_workspace_scope = _resolve_ai_job_workspace_scope(aj)
+        # Server-resolved QA workspace baseline (SI-887).  Top-level field wins;
+        # the input_context copy is the fallback for older payload shapes.
+        # When absent, prepare_workspace keeps its legacy requirement_key
+        # derivation so this daemon stays compatible with older servers.
+        qa_ws_source = aj.get("qa_workspace_source") or (
+            input_ctx.get("qa_workspace_source") if isinstance(input_ctx, dict) else None
+        ) or {}
 
         reporter_url = f"{conn.server_url.rstrip('/')}/api/v1/runtimes/{conn.runtime_id}/ai-jobs/{job_id}"
         # Use workspace-level key (project:requirement or project:job_id) so AI jobs
@@ -9615,6 +9818,8 @@ class RuntimeDaemon:
                 requirement_workflow_id=None,
                 requirement_key=requirement_key,
                 graph_type="ai_job",
+                workspace_source_mode=qa_ws_source.get("mode"),
+                workspace_branch=qa_ws_source.get("branch"),
             )
             workspace_path = await self.workspace_manager.prepare_workspace(
                 project_info, fake_task,

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/forgexa_cli/main.py

@@ -877,6 +877,8 @@ def _read_pid_file(path: Path) -> int | None:
 
 
 def _process_is_running(pid: int) -> bool:
+    if sys.platform == "win32":
+        return _windows_process_is_running(pid)
     try:
         os.kill(pid, 0)
     except ProcessLookupError:
@@ -886,6 +888,31 @@ def _process_is_running(pid: int) -> bool:
     return True
 
 
+def _windows_process_is_running(pid: int) -> bool:
+    """Check whether `pid` is alive on Windows, without signaling it.
+
+    os.kill(pid, 0) is NOT a safe existence probe on Windows: signal 0 is
+    CTRL_C_EVENT, so it calls GenerateConsoleCtrlEvent (or TerminateProcess
+    for other signal values) instead of a POSIX-style no-op check. Against a
+    stale/recycled PID — e.g. left on disk from before an upgrade — this can
+    raise an arbitrary WinError (such as the WinError 11 "incorrect program
+    format" some users hit) instead of a clean "no such process" result,
+    crashing `forgexa daemon start` with an unreadable traceback. Shell out
+    to `tasklist` instead, mirroring the existing `taskkill`-based approach
+    in _stop_daemon_by_pid, so we only ever query — never signal.
+    """
+    try:
+        result = subprocess.run(
+            ["tasklist", "/FI", f"PID eq {pid}", "/NH"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return str(pid) in result.stdout
+
+
 def _cleanup_daemon_pid_files(pid: int | None = None) -> None:
     for path in _daemon_pid_files():
         recorded_pid = _read_pid_file(path)
@@ -1426,12 +1453,18 @@ def cmd_daemon_restart(args: argparse.Namespace) -> None:
 def cmd_daemon_start(args: argparse.Namespace) -> None:
     """Start the local daemon (agent runtime)."""
     # Refuse to start a second instance
+    stale_pids = [p for p in (_read_pid_file(f) for f in _daemon_pid_files()) if p is not None]
     existing_pid = _find_running_daemon_pid()
     if existing_pid is not None:
         print(f"Daemon is already running (PID {existing_pid}).")
         print("Use 'forgexa daemon restart' to restart it.")
         sys.exit(1)
 
+    if stale_pids:
+        print(f"Cleared a stale daemon record (PID {stale_pids[0]}) left over from a previous run.")
+        print("(Tip: stop the daemon first if you upgrade forgexa outside of 'forgexa upgrade'.)")
+        print()
+
     server_url = getattr(args, "server_url", None) or _api_url()
     os.environ["DAEMON_SERVER_URL"] = server_url
 

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/forgexa_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.21.7
+Version: 1.22.0
 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
@@ -137,6 +137,26 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### One-Shot Upgrade Script (recommended for production runtimes)
+
+`forgexa upgrade` alone only auto-restarts the daemon if it was already running in background mode *right before* the upgrade started — if it had already stopped for any other reason (crash, manual stop, first-time setup), you're left to restart it yourself. [`cli/scripts/upgrade.sh`](scripts/upgrade.sh) (macOS/Linux) and [`cli/scripts/upgrade.ps1`](scripts/upgrade.ps1) (Windows) wrap the full, correct sequence explicitly so the daemon is deterministically stopped, upgraded, and started again in the background every time, regardless of its state going in:
+
+```bash
+# macOS / Linux
+./cli/scripts/upgrade.sh
+./cli/scripts/upgrade.sh --target-version 1.21.7
+./cli/scripts/upgrade.sh --server-url https://api.forgexa.net --login
+```
+
+```powershell
+# Windows
+.\cli\scripts\upgrade.ps1
+.\cli\scripts\upgrade.ps1 -TargetVersion 1.21.7
+.\cli\scripts\upgrade.ps1 -ServerUrl https://api.forgexa.net -Login
+```
+
+Steps: `daemon stop` (no-op if not running) → `upgrade` → `daemon start -d` → optional `login` → `daemon status`. Login is skipped by default (the previously saved session is reused) unless you pass `--email`/`--password` (`-Email`/`-Password`), set `FORGEXA_LOGIN_EMAIL`/`FORGEXA_LOGIN_PASSWORD`, or pass `--login`/`-Login` to be prompted interactively. Run with `--help`/`Get-Help .\upgrade.ps1` for all options.
+
 ### Automatic Background Upgrade
 
 By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/pyproject.toml

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

{forgexa_cli-1.21.7 → forgexa_cli-1.22.0}/tests/test_auth_and_runtime_commands.py

@@ -98,6 +98,132 @@ def test_windows_batch_agent_commands_expand_indexed_launcher_path(
     assert "& ($forgexa_command[0]) @forgexa_arguments" in script
 
 
+def test_windows_process_is_running_true_when_tasklist_finds_pid(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        main.subprocess,
+        "run",
+        lambda *a, **k: SimpleNamespace(stdout="python.exe   4242 Console   1   12,345 K", returncode=0),
+    )
+
+    assert main._windows_process_is_running(4242) is True
+
+
+def test_windows_process_is_running_false_when_tasklist_reports_no_match(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        main.subprocess,
+        "run",
+        lambda *a, **k: SimpleNamespace(
+            stdout="INFO: No tasks are running which match the specified criteria.",
+            returncode=0,
+        ),
+    )
+
+    assert main._windows_process_is_running(4242) is False
+
+
+def test_windows_process_is_running_queries_tasklist_with_pid_filter(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls: list[list[str]] = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append(cmd)
+        return SimpleNamespace(stdout="", returncode=0)
+
+    monkeypatch.setattr(main.subprocess, "run", fake_run)
+
+    main._windows_process_is_running(4242)
+
+    assert calls == [["tasklist", "/FI", "PID eq 4242", "/NH"]]
+
+
+def test_windows_process_is_running_false_on_oserror(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A stale/recycled PID can make Windows raise arbitrary OSErrors (e.g. WinError 11).
+
+    This must resolve to "not running" instead of propagating and crashing
+    `forgexa daemon start` with an unreadable traceback.
+    """
+
+    def boom(*a, **k):
+        raise OSError(11, "incorrect program format")
+
+    monkeypatch.setattr(main.subprocess, "run", boom)
+
+    assert main._windows_process_is_running(4242) is False
+
+
+def test_windows_process_is_running_false_on_timeout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """subprocess.TimeoutExpired is NOT an OSError subclass — must be caught separately."""
+
+    def boom(*a, **k):
+        raise main.subprocess.TimeoutExpired(cmd="tasklist", timeout=5)
+
+    monkeypatch.setattr(main.subprocess, "run", boom)
+
+    assert main._windows_process_is_running(4242) is False
+
+
+def test_process_is_running_dispatches_to_windows_helper_on_win32(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(main.sys, "platform", "win32")
+    monkeypatch.setattr(main, "_windows_process_is_running", lambda pid: pid == 4242)
+
+    assert main._process_is_running(4242) is True
+    assert main._process_is_running(1) is False
+
+
+def test_cmd_daemon_start_clears_stale_pid_with_friendly_message(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.delenv("FORGEXA_TOKEN", raising=False)
+    monkeypatch.delenv("FORGEXA_SERVER_URL", raising=False)
+    monkeypatch.delenv("DAEMON_SERVER_URL", raising=False)
+    monkeypatch.delenv("DAEMON_API_TOKEN", raising=False)
+    monkeypatch.setattr(main, "_SERVER_URL_OVERRIDE", None)
+    # Simulate a PID left on disk from before an upgrade that no longer resolves
+    # to a running process, without depending on real OS PID reuse semantics.
+    monkeypatch.setattr(main, "_process_is_running", lambda pid: False)
+    monkeypatch.setattr(main.subprocess, "Popen", lambda *a, **k: SimpleNamespace(pid=12345))
+
+    (tmp_path / ".forgexa-daemon.pid").write_text("424242")
+
+    buffer = io.StringIO()
+    with contextlib.redirect_stdout(buffer):
+        main.cmd_daemon_start(SimpleNamespace(detach=True, server_url=None))
+
+    output = buffer.getvalue()
+    assert "Cleared a stale daemon record (PID 424242) left over from a previous run." in output
+    assert "forgexa upgrade" in output
+
+
+def test_cmd_daemon_start_no_stale_pid_message_on_clean_start(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.delenv("FORGEXA_TOKEN", raising=False)
+    monkeypatch.delenv("FORGEXA_SERVER_URL", raising=False)
+    monkeypatch.delenv("DAEMON_SERVER_URL", raising=False)
+    monkeypatch.delenv("DAEMON_API_TOKEN", raising=False)
+    monkeypatch.setattr(main, "_SERVER_URL_OVERRIDE", None)
+    monkeypatch.setattr(main.subprocess, "Popen", lambda *a, **k: SimpleNamespace(pid=12345))
+
+    buffer = io.StringIO()
+    with contextlib.redirect_stdout(buffer):
+        main.cmd_daemon_start(SimpleNamespace(detach=True, server_url=None))
+
+    assert "stale daemon record" not in buffer.getvalue()
+
+
 def test_get_retries_once_after_refresh_on_401(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,