fix(desktop): make dev server start idempotent and agent-safe

dev.sh start no longer stops a healthy server, uses start_new_session
for macOS detach, flock to prevent parallel start races, and adds status.
main.py exits 0 when ABI_DESKTOP_PORT is set and our app is already healthy.

Author: jravenel

libs/naas-abi/naas_abi/apps/desktop/AGENTS.md

@@ -353,10 +353,13 @@ Conventions and seams:
 Run only one dev instance at a time (the embedded Oxigraph graph uses on-disk RocksDB).
 
 ```bash
-# from repo root — detached, survives agent shells; opens nothing automatically
+# from repo root — idempotent; safe for parallel agents; never kills a healthy server
 make dev-desktop
 
-# stop supervisor + server + clear stale locks
+# check health + PIDs without restarting
+libs/naas-abi/naas_abi/apps/desktop/scripts/dev.sh status
+
+# stop supervisor + server (only when you intend to shut down)
 libs/naas-abi/naas_abi/apps/desktop/scripts/dev.sh stop
 ```
 
@@ -365,8 +368,10 @@ libs/naas-abi/naas_abi/apps/desktop/scripts/dev.sh stop
 - **Meta:** `~/.abi-desktop/server.json` (URL, port, worker PID)
 - **Hot reload:** Python under `desktop/` restarts on save. Frontend is vanilla JS/CSS under
   `gui/web/` — refresh the browser after edits; no bundler.
-- **Instance lock:** skipped when `--reload` is active; `dev.sh` kills stale listeners and
-  clears `instance.lock` before start. Do not run two dev servers against the same data dir.
+- **Instance lock:** skipped when `--reload` is active. `dev.sh start` is idempotent: if
+  `/api/health` returns 200, it prints the URL and exits 0 without stopping anything.
+  Only `dev.sh stop` tears down the supervisor. Do not run two dev servers against
+  different data dirs on the same port.
 
 Foreground browser dev (no supervisor):
 

libs/naas-abi/naas_abi/apps/desktop/README.md

@@ -20,18 +20,46 @@ uv sync --all-extras
 
 Recommended daily workflow: run from source in your browser. No PyInstaller rebuild required.
 
+**Canonical command** (idempotent: safe to run repeatedly; never kills a healthy server):
+
 ```bash
 # from repo root — detached supervisor, Python hot reload, crash restart
 make dev-desktop
+# same as:
+libs/naas-abi/naas_abi/apps/desktop/scripts/dev.sh start
+# or:
+libs/naas-abi/naas_abi/apps/desktop/scripts/ensure-dev.sh
+```
+
+Check status without restarting:
+
+```bash
+libs/naas-abi/naas_abi/apps/desktop/scripts/dev.sh status
+```
 
-# stop the dev server
+Stop only when you explicitly want to shut down:
+
+```bash
 libs/naas-abi/naas_abi/apps/desktop/scripts/dev.sh stop
 ```
 
 Open [http://127.0.0.1:54242](http://127.0.0.1:54242). Override the port with `ABI_DESKTOP_PORT` if needed.
 
 Logs: `~/.abi-desktop/server.log`. Server metadata (URL, PID): `~/.abi-desktop/server.json`.
 
+### Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `already running at http://127.0.0.1:54242` | Healthy server on port | No action needed; open the URL |
+| `port 54242 in use by a non-ABI process` | Another app holds the port | Quit that app, or `dev.sh stop`, or set `ABI_DESKTOP_PORT` |
+| `supervisor running but server unhealthy` | Stuck/crashed worker | `dev.sh stop` then `dev.sh start` |
+| Server dies when a Cursor agent exits | Old supervisor not detached | Update to latest `dev.sh` (uses `start_new_session`) |
+| `instance.lock` / graph LOCK errors | Two dev servers on same data dir | Run only one `dev.sh start`; use `dev.sh stop` to reset |
+| Exit code 143 / SIGTERM in `server.log` | Agent killed the process group | Use `make dev-desktop` (detached supervisor), not foreground `uv run` in agent shells |
+
+**Do not** call `dev.sh stop` unless you intend to shut down. Parallel `dev.sh start` calls are safe: they detect health and exit 0 without restarting.
+
 Use the **workspace switcher** (icon rail top: logo only, Nexus-style) to open or switch IDE workspaces. The **status bar** (left) shows the current workspace basename and git branch as read-only context. Each workspace is a folder on disk (e.g. `~/abi`). In browser dev, **Open Folder…** accepts a typed path; in the pywebview app, **Browse…** opens the native folder picker.
 
 **Reload behavior:**

libs/naas-abi/naas_abi/apps/desktop/main.py

@@ -155,6 +155,10 @@ def resolve_server_port(*, allow_fallback: bool = True) -> int:
             )
             raise SystemExit(1)
         if not _port_available(port):
+            if _is_abi_desktop_on_port(port):
+                url = _read_server_url() or f"http://127.0.0.1:{port}"
+                print(f"{APP_NAME} is already running at {url}")
+                raise SystemExit(0)
             print(_port_in_use_message(port), file=sys.stderr)
             raise SystemExit(1)
         return port
@@ -165,11 +169,8 @@ def resolve_server_port(*, allow_fallback: bool = True) -> int:
 
     if _is_abi_desktop_on_port(port):
         url = _read_server_url() or f"http://127.0.0.1:{port}"
-        print(
-            f"{APP_NAME} is already serving {url} (see ~/.abi-desktop/server.json).",
-            file=sys.stderr,
-        )
-        raise SystemExit(1)
+        print(f"{APP_NAME} is already running at {url}")
+        raise SystemExit(0)
 
     if allow_fallback and _port_available(port + 1):
         print(

libs/naas-abi/naas_abi/apps/desktop/main_test.py

@@ -125,6 +125,27 @@ def test_resolve_server_port_in_use_exits(
     assert "ABI_DESKTOP_PORT" in err
 
 
+def test_resolve_server_port_env_already_running_abi(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    ephemeral_default_port: int,
+) -> None:
+    """When ABI_DESKTOP_PORT is set and our app is healthy, exit 0 (idempotent)."""
+    from unittest.mock import patch
+
+    port = ephemeral_default_port
+    monkeypatch.setenv("ABI_DESKTOP_PORT", str(port))
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", port))
+        with patch("desktop.main._is_abi_desktop_on_port", return_value=True):
+            with patch("desktop.main._read_server_url", return_value=f"http://127.0.0.1:{port}"):
+                with pytest.raises(SystemExit) as exc:
+                    resolve_server_port(allow_fallback=False)
+    assert exc.value.code == 0
+    out = capsys.readouterr().out
+    assert "already running" in out
+
+
 @pytest.fixture
 def bound_port() -> Iterator[int]:
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock: