@agentikos/omega-os 0.19.38 → 0.19.39

package/omega/Agentik_Engine/omega_engine/tui.py

@@ -462,46 +462,180 @@ def _arrow_menu() -> int:
     # `omega_engine.provider_state` module both can read.
     from omega_engine.provider_state import active_provider as _active_provider
 
+    # v0.19.39 — chat-first redesign. The TUI now opens on CONVERSATIONS
+    # (live tmux sessions: AISB chat, Hermès chat, active Oracles per
+    # project, active Workers per task) with ●/○ status dots. Setup,
+    # config, infra, audits, scrape, etc. move into sub-menus opened from
+    # a short "MENU" section. Reasoning: the user spends 99% of their
+    # time in conversations — the menu should reflect that, not bury the
+    # chats below 6 sections of admin options.
+    DOT_ON  = f"{ORANGE}●{RST}"     # alive
+    DOT_OFF = f"{MUTED}○{RST}"      # not running
+
+    def _dot(alive: bool) -> str:
+        return DOT_ON if alive else DOT_OFF
+
+    def _conv_label(name: str, hint: str, alive: bool) -> str:
+        """Conversation row: `<dot>  <name>  <dim hint>`."""
+        dot = _dot(alive)
+        return f"  {dot}  {name:<32}{DIM}{hint}{RST}"
+
+    def _paperclip_status_quick() -> tuple[bool, str]:
+        """Lightweight inline Paperclip probe — short timeout, no raise.
+        Returns (alive, hint). Hint is empty when down, ``localhost:8080``
+        (or whatever port the bridge reports) when up. Uses the new
+        ``paperclip_bridge.is_running()`` from chantier 4 when present;
+        falls back gracefully to a plain TCP probe.
+        """
+        try:
+            from omega_engine.paperclip_bridge import is_running as _pcst
+            st = _pcst(HOME)
+            if getattr(st, "running", False):
+                port = getattr(st, "port", None) or 8080
+                return True, f"localhost:{port}"
+        except Exception:  # noqa: BLE001
+            # Fallback: a 200ms TCP probe to 127.0.0.1:8080.
+            import socket as _s
+            try:
+                with _s.create_connection(("127.0.0.1", 8080), timeout=0.2):
+                    return True, "localhost:8080"
+            except OSError:
+                pass
+        return False, ""
+
+    def _active_oracles_and_workers() -> tuple[list, list]:
+        """Categorize live tmux sessions into (oracles, workers).
+        Each entry is the ``TmuxSession`` instance."""
+        all_sessions = tmux.list_sessions(HOME)
+        oracles = sorted([s for s in all_sessions if s.category == "oracle"],
+                         key=lambda x: x.name)
+        workers = sorted([s for s in all_sessions if s.category == "worker"],
+                         key=lambda x: x.name)
+        return oracles, workers
+
     def _build_items() -> list[tuple[str, str]]:
-        """Return (display, action_key) — section headers have key '__sep__'."""
+        """Return (display, action_key) — section headers have key '__sep__'.
+
+        v0.19.39 layout (chat-first):
+          1. CONVERSATIONS  — AISB / Hermès / live Oracles / live Workers
+          2. QUICK ACTIONS  — new chat, new project, run mission, Paperclip
+          3. MENU           — sub-menus (audits, setup, infra, health)
+          4. EXIT
+        """
         provider = _active_provider()
-        sessions = tmux.list_sessions(HOME)
-        return [
-            (_section("CHAT"),                                          "__sep__"),
-            (_label("AISB master chat",  "→ claude (Max OAuth)"),       "open:aisb"),
-            (_label("Hermès companion",  "→ claude (Anthropic API)"),   "open:hermes"),
-            (_label("Switch LLM",        f"current: {provider}"),       "switch:provider"),
-            ("",                                                        "__sep__"),
-            (_section("PROJECTS"),                                      "__sep__"),
-            (_label("New project",       "Genesis pipeline"),           "genesis:new"),
-            (_label("Open project shell"),                              "project:open"),
-            ("",                                                        "__sep__"),
-            (_section("AUDITS & MISSIONS"),                             "__sep__"),
-            (_label("Run a mission",     "verified completion"),        "run:mission"),
-            (_label("Quality Arsenal",   "17 forensic audits"),         "audit:menu"),
-            ("",                                                        "__sep__"),
-            (_section("INFRASTRUCTURE"),                                "__sep__"),
-            (_label("Sessions",          f"{len(sessions)} active"),    "sessions:list"),
-            (_label("Accounts",          "Claude Max pool"),            "accounts:menu"),
-            (_label("Vault",             "encrypted secrets"),          "vault:menu"),
-            ("",                                                        "__sep__"),
-            (_section("HEALTH"),                                        "__sep__"),
-            (_label("omega doctor",      "full health check"),          "cmd:doctor"),
-            (_label("omega status",      "task state"),                 "cmd:status"),
-            ("",                                                        "__sep__"),
-            (_section("SCRAPE"),                                        "__sep__"),
-            (_label("Stealth scrape",    "CloakBrowser"),               "scrape:cloak"),
-            (_label("Fast scrape",       "Scrapling"),                  "scrape:scrapling"),
-            ("",                                                        "__sep__"),
-            (_section("GOVERNANCE (Paperclip L0)"),                     "__sep__"),
-            (_label("Paperclip dashboard","web UI for 14 agents"),      "paperclip:dashboard"),
-            (_label("Paperclip status",  "bridge health"),              "paperclip:status"),
-            (_label("Paperclip register","(re)sync OmegaOS company"),   "paperclip:register"),
-            ("",                                                        "__sep__"),
-            (_section("EXIT"),                                          "__sep__"),
-            (_label("Detach",            "session keeps running"),      "detach"),
-            (_label("Quit Omega",        "kills the tmux session"),     "quit:kill"),
-        ]
+        aisb_alive = tmux.omega_window_alive("aisb")
+        hermes_alive = tmux.omega_window_alive("hermes")
+        oracles, workers = _active_oracles_and_workers()
+        paperclip_alive, paperclip_hint = _paperclip_status_quick()
+
+        items: list[tuple[str, str]] = []
+
+        # ── CONVERSATIONS ───────────────────────────────────────────────
+        items.append((_section("CONVERSATIONS"), "__sep__"))
+        items.append((_conv_label("AISB master",  "claude (Max OAuth)",     aisb_alive),   "open:aisb"))
+        items.append((_conv_label("Hermès",       "claude (Anthropic API)", hermes_alive), "open:hermes"))
+
+        # Per-project live oracles + workers (only when there are any —
+        # don't waste a row when the user has nothing running).
+        if oracles or workers:
+            items.append(("", "__sep__"))
+        if oracles:
+            items.append((f"  {DIM}— Active Oracles ({len(oracles)}) —{RST}", "__sep__"))
+            for s in oracles:
+                proj = s.project or "?"
+                hint = f"project: {proj}"
+                items.append((_conv_label(s.name, hint, True), f"attach:{s.name}"))
+        if workers:
+            items.append((f"  {DIM}— Active Workers ({len(workers)}) —{RST}", "__sep__"))
+            for s in workers:
+                # Extract task from `<proj>-worker-N-<task>`.
+                task = s.name.split("worker-", 1)[-1].split("-", 1)[-1] if "worker-" in s.name else "?"
+                hint = f"task: {task}"
+                items.append((_conv_label(s.name, hint, True), f"attach:{s.name}"))
+
+        items.append(("", "__sep__"))
+
+        # ── QUICK ACTIONS ───────────────────────────────────────────────
+        items.append((_section("QUICK ACTIONS"), "__sep__"))
+        items.append((_label("+ New AISB chat",     "fresh session"),       "open:aisb:new"))
+        items.append((_label("+ New Hermès chat",   "fresh session"),       "open:hermes:new"))
+        items.append((_label("+ New project",       "Genesis pipeline"),    "genesis:new"))
+        items.append((_label("Run a mission",       "verified completion"), "run:mission"))
+        # Paperclip dashboard with live status indicator.
+        pclbl = f"Paperclip dashboard"
+        pcdot = _dot(paperclip_alive)
+        pchint = paperclip_hint if paperclip_alive else "not running"
+        items.append((f"  {pcdot}  {pclbl:<32}{DIM}{pchint}{RST}", "paperclip:dashboard"))
+
+        items.append(("", "__sep__"))
+
+        # ── MENU (sub-menus for everything else) ────────────────────────
+        items.append((_section("MENU"), "__sep__"))
+        items.append((_label("Quality Arsenal",       "17 forensic audits"),    "submenu:audits"))
+        items.append((_label("Setup & config",        f"LLM: {provider}"),      "submenu:setup"))
+        items.append((_label("Infrastructure",        "sessions, scrape"),      "submenu:infra"))
+        items.append((_label("Health checks",         "doctor, status"),        "submenu:health"))
+        items.append((_label("Paperclip governance",  "register, status"),      "submenu:paperclip"))
+
+        items.append(("", "__sep__"))
+
+        # ── EXIT ────────────────────────────────────────────────────────
+        items.append((_section("EXIT"), "__sep__"))
+        items.append((_label("Detach",         "session keeps running"), "detach"))
+        items.append((_label("Quit Omega",     "kills the tmux session"), "quit:kill"))
+
+        return items
+
+    def _submenu_items(name: str) -> list[tuple[str, str]]:
+        """Return (display, action_key) for one of the named sub-menus.
+        Every sub-menu ends with a synthetic '← back' row that aborts the
+        cascaded fzf with key 'back'."""
+        if name == "audits":
+            return [
+                (_section("QUALITY ARSENAL"),                              "__sep__"),
+                (_label("List all 17 audits"),                              "audit:menu"),
+                (_label("Run an audit",  "interactive"),                   "audit:run"),
+                ("",                                                        "__sep__"),
+                (_label("← back"),                                          "back"),
+            ]
+        if name == "setup":
+            return [
+                (_section("SETUP & CONFIG"),                               "__sep__"),
+                (_label("Switch LLM provider"),                             "switch:provider"),
+                (_label("Accounts",      "Claude Max pool"),                "accounts:menu"),
+                (_label("Vault",         "encrypted secrets"),              "vault:menu"),
+                ("",                                                        "__sep__"),
+                (_label("← back"),                                          "back"),
+            ]
+        if name == "infra":
+            return [
+                (_section("INFRASTRUCTURE"),                               "__sep__"),
+                (_label("List tmux sessions"),                              "sessions:list"),
+                (_label("Open project shell"),                              "project:open"),
+                ("",                                                        "__sep__"),
+                (_label("Stealth scrape", "CloakBrowser"),                  "scrape:cloak"),
+                (_label("Fast scrape",   "Scrapling"),                      "scrape:scrapling"),
+                ("",                                                        "__sep__"),
+                (_label("← back"),                                          "back"),
+            ]
+        if name == "health":
+            return [
+                (_section("HEALTH"),                                       "__sep__"),
+                (_label("omega doctor",  "full health check"),              "cmd:doctor"),
+                (_label("omega status",  "task state"),                     "cmd:status"),
+                ("",                                                        "__sep__"),
+                (_label("← back"),                                          "back"),
+            ]
+        if name == "paperclip":
+            return [
+                (_section("PAPERCLIP GOVERNANCE (L0)"),                    "__sep__"),
+                (_label("Open dashboard"),                                  "paperclip:dashboard"),
+                (_label("Status",        "bridge health"),                  "paperclip:status"),
+                (_label("Register",      "(re)sync OmegaOS company"),       "paperclip:register"),
+                ("",                                                        "__sep__"),
+                (_label("← back"),                                          "back"),
+            ]
+        return [(_label("← back"), "back")]
 
     def _run_inline(cmd_argv, *, shell: bool = False) -> None:
         os.system("clear")
@@ -525,23 +659,29 @@ def _arrow_menu() -> int:
         except (EOFError, KeyboardInterrupt):
             return ""
 
-    while True:
-        items = _build_items()
-        # v0.19.37 — bulletproof matching via tab-delimited index column.
-        # fzf with --ansi STRIPS escape codes from stdout, which broke
-        # the old `display == pick` exact-string match (every pick fell
-        # through, menu just reloaded). Now we prefix each line with a
-        # stable index (`<i>\t<display>`) and use --with-nth=2.. so fzf
-        # only DISPLAYS the second column but RETURNS the full line.
-        # We split off the index and look up the action — survives any
-        # ANSI/whitespace transformation fzf might apply.
+    def _pick(items: list[tuple[str, str]],
+              header_extra: str = "") -> str | None:
+        """Render one fzf pass over ``items`` and return the chosen
+        action key (the second element of the picked tuple), or ``None``
+        on Esc / Ctrl-C / error.
+
+        Skips section headers and blank rows automatically — the caller
+        never has to worry about ``__sep__`` picks.
+
+        v0.19.37 lock-in: input is tab-delimited ``<idx>\\t<display>``,
+        fzf --with-nth=2.. shows only the visual column, and we parse
+        the index column out of stdout — survives any ANSI/whitespace
+        transformation fzf applies.
+        """
         lines = []
-        for i, (disp, key) in enumerate(items):
+        for i, (disp, _key) in enumerate(items):
             lines.append(f"{i}\t{disp}")
         header = (
             f"{ORANGE}{BOLD}Ω  Omega OS v{__version__}{RST}  "
             f"{MUTED}•  ↑↓ navigate  •  ↵ pick  •  / search  •  Esc refresh{RST}"
         )
+        if header_extra:
+            header = f"{header}\n{MUTED}{header_extra}{RST}"
         try:
             proc = subprocess.run(
                 ["fzf",
@@ -577,27 +717,50 @@ def _arrow_menu() -> int:
                 input="\n".join(lines), capture_output=True, text=True,
             )
         except (KeyboardInterrupt, subprocess.SubprocessError):
-            return 0
+            return None
         if proc.returncode != 0:
-            # Esc → refresh.
-            continue
+            return None
         pick = proc.stdout.rstrip("\n")
-        # Parse the index column. The tab is always the first \t in the
-        # picked line (the rest of the display may contain colour codes
-        # but no tabs).
         if "\t" not in pick:
-            continue
-        idx_str, _disp_part = pick.split("\t", 1)
+            return None
+        idx_str, _ = pick.split("\t", 1)
         try:
             idx = int(idx_str)
         except ValueError:
-            continue
+            return None
         if not (0 <= idx < len(items)):
-            continue
+            return None
         action = items[idx][1]
         if action == "__sep__":
-            # User picked a section header — silent reroll.
+            return None
+        return action
+
+    def _open_submenu(name: str) -> str | None:
+        """Render a sub-menu in a loop until the user picks an action OR
+        chooses 'back'. Returns the action key to dispatch (the caller
+        runs it), or None when the user backs out / Esc'd.
+        """
+        while True:
+            sub_items = _submenu_items(name)
+            picked = _pick(sub_items, header_extra=f"sub-menu: {name}  ·  Esc/← back to main")
+            if picked is None or picked == "back":
+                return None
+            return picked
+
+    while True:
+        items = _build_items()
+        action = _pick(items)
+        if action is None:
+            # Esc → just refresh the conversations panel (cheap — re-renders
+            # with live tmux state).
             continue
+        # Sub-menu indirection: when the user picks a sub-menu, render it
+        # in its own loop until they pick a real action or back out.
+        if action.startswith("submenu:"):
+            sub_name = action.split(":", 1)[1]
+            action = _open_submenu(sub_name)
+            if action is None:
+                continue
 
         # === Dispatch ===
         if action == "detach":
@@ -606,19 +769,50 @@ def _arrow_menu() -> int:
         if action == "quit:kill":
             subprocess.run(["tmux", "kill-session", "-t", "Omega"])
             return 0
-        if action == "open:aisb":
-            # v0.19.31 — open as a WINDOW in Omega, not a separate session.
-            # User stays in Omega; Ctrl-b 0 returns to menu, Ctrl-b d
-            # detaches the whole Omega (and `omega` brings them back).
+        # v0.19.39 — attach to a live Oracle / Worker tmux session. The
+        # menu lists them as `attach:<session_name>`. We use
+        # `select-window` when the session is already a window inside
+        # Omega; otherwise we switch the client to that session.
+        if action.startswith("attach:"):
+            target = action.split(":", 1)[1]
+            # If the target is a window of Omega, just select it. Else
+            # switch-client to that session (works under nested tmux).
+            wnames = subprocess.run(
+                ["tmux", "list-windows", "-t", "Omega", "-F", "#W"],
+                capture_output=True, text=True,
+            )
+            if (wnames.returncode == 0
+                    and target in (wnames.stdout or "").splitlines()):
+                subprocess.run(["tmux", "select-window",
+                                "-t", f"Omega:{target}"])
+            else:
+                # Switch to the foreign session. Use switch-client (works
+                # when we're already inside a tmux client) or fall back to
+                # attach for non-tmux contexts.
+                rc = subprocess.run(
+                    ["tmux", "switch-client", "-t", target],
+                    capture_output=True,
+                ).returncode
+                if rc != 0:
+                    _run_inline(f"echo '  cannot attach to {target} — is it alive?' "
+                                f"&& tmux has-session -t {target} && "
+                                f"echo '  tmux says: yes' || echo '  tmux says: no'",
+                                shell=True)
+            continue
+        # v0.19.39 — "+ New" actions: kill existing chat window first so
+        # the user gets a clean fresh session.
+        if action in ("open:aisb", "open:aisb:new"):
+            force = (action == "open:aisb:new")
             persona = HOME / "Agentik_SSOT" / "agents" / "aisb" / "CLAUDE.md"
             ctx_dir = tmux._ensure_chat_context_dir(HOME, "aisb-master", persona)
             tmux.spawn_chat_in_omega(
                 "aisb", ctx_dir=ctx_dir, run_command="claude",
-                force_replace=False,
+                force_replace=force,
             )
             subprocess.run(["tmux", "select-window", "-t", "Omega:aisb"])
             continue
-        if action == "open:hermes":
+        if action in ("open:hermes", "open:hermes:new"):
+            force = (action == "open:hermes:new")
             persona = HOME / "Agentik_SSOT" / "docs" / "LAYERS.md"
             ctx_dir = tmux._ensure_chat_context_dir(HOME, "hermes", persona)
             try:
@@ -632,10 +826,18 @@ def _arrow_menu() -> int:
                        if api_key else "claude")
             tmux.spawn_chat_in_omega(
                 "hermes", ctx_dir=ctx_dir, run_command=run_cmd,
-                force_replace=False,
+                force_replace=force,
             )
             subprocess.run(["tmux", "select-window", "-t", "Omega:hermes"])
             continue
+        if action == "audit:run":
+            audit_id = _prompt("audit id (codeaudit, uiuxaudit, flowaudit, ...)")
+            if audit_id:
+                _run_inline([OMEGA_BIN, "audit", audit_id])
+            continue
+        # (v0.19.31 open:aisb / open:hermes legacy handlers removed in
+        # v0.19.39 — the new unified handlers above (which accept both
+        # plain and `:new` variants) cover the same surface.)
         if action == "switch:provider":
             _run_inline([OMEGA_BIN, "switch"]); continue
         if action == "genesis:new":

package/omega/Agentik_Engine/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omega-engine"
-version = "0.19.38"
+version = "0.19.39"
 description = "The Omega OS orchestration engine — event-sourced, verified-completion agent graphs."
 readme = "README.md"
 requires-python = ">=3.11"

package/omega/Agentik_Engine/tests/test_paperclip_status.py

@@ -0,0 +1,142 @@
+"""Tests for omega_engine.paperclip_bridge.is_running().
+
+Locks in the live status probe contract so the TUI can render ●/○ next to
+the Paperclip menu items. Five detection paths covered:
+
+  1. Empty PAPERCLIP_HOME      → not running (detection="none")
+  2. Stale pidfile             → not running
+  3. Live pidfile (self PID)   → running   (detection="pidfile")
+  4. No pidfile + open socket  → running   (detection="port-scan")
+  5. Running case sets url     → http://localhost:<port>
+"""
+from __future__ import annotations
+
+import os
+import socket
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from omega_engine import paperclip_bridge as P
+
+
+def _free_port() -> int:
+    """Allocate (and release) an ephemeral TCP port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class TestIsRunningDetectionPaths(unittest.TestCase):
+    """Each of the three detection paths plus the URL invariant."""
+
+    def test_no_pidfile_no_port_returns_not_running(self):
+        """Empty PAPERCLIP_HOME + closed port → running=False, detection=none."""
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.dict(os.environ, {"PAPERCLIP_HOME": tmp}, clear=False):
+                # Pick a port nothing is listening on (allocate then release).
+                port = _free_port()
+                status = P.is_running(port=port)
+            self.assertFalse(status.running)
+            self.assertEqual(status.detection, "none")
+            self.assertIsNone(status.pid)
+            self.assertIsNone(status.port)
+            self.assertIsNone(status.url)
+
+    def test_stale_pidfile_returns_not_running(self):
+        """Pidfile points at a dead PID → running=False (falls through to port,
+        which is also closed in this test)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.dict(os.environ, {"PAPERCLIP_HOME": tmp}, clear=False):
+                run_dir = Path(tmp) / "run"
+                run_dir.mkdir(parents=True, exist_ok=True)
+                # 99999999 is virtually guaranteed to be unused on Linux
+                # (default PID max is 4194304); we also mock os.kill to be
+                # sure across any host's PID-recycling weirdness.
+                (run_dir / "dashboard.pid").write_text("99999999\n")
+
+                def fake_kill(pid: int, sig: int) -> None:
+                    if pid == 99999999:
+                        raise ProcessLookupError(pid)
+                    # delegate to the real os.kill for any other pid
+                    return os._real_kill(pid, sig)  # pragma: no cover
+
+                # Stash the real kill (in case fake_kill ever delegates).
+                os._real_kill = os.kill  # type: ignore[attr-defined]
+                try:
+                    port = _free_port()
+                    with mock.patch("omega_engine.paperclip_bridge.os.kill",
+                                    side_effect=fake_kill):
+                        status = P.is_running(port=port)
+                finally:
+                    del os._real_kill  # type: ignore[attr-defined]
+            self.assertFalse(status.running)
+            self.assertEqual(status.detection, "none")
+            self.assertIsNone(status.pid)
+
+    def test_live_pidfile_returns_running(self):
+        """Pidfile points at this test process (alive) → running=True,
+        detection='pidfile', does NOT touch the network."""
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.dict(os.environ, {"PAPERCLIP_HOME": tmp}, clear=False):
+                run_dir = Path(tmp) / "run"
+                run_dir.mkdir(parents=True, exist_ok=True)
+                self_pid = os.getpid()
+                (run_dir / "dashboard.pid").write_text(f"{self_pid}\n")
+                # Patch socket so we'd notice if the code accidentally tried
+                # to connect (it shouldn't — pidfile hit returns immediately).
+                with mock.patch("omega_engine.paperclip_bridge.socket.socket") \
+                        as sock_cls:
+                    status = P.is_running(port=8080)
+                    sock_cls.assert_not_called()
+            self.assertTrue(status.running)
+            self.assertEqual(status.detection, "pidfile")
+            self.assertEqual(status.pid, self_pid)
+            self.assertEqual(status.port, 8080)
+
+    def test_port_scan_fallback_running(self):
+        """No pidfile, but a socket IS listening on the probe port →
+        running=True, detection='port-scan', pid=None."""
+        # Bind a real listener on an ephemeral port for the duration of
+        # the probe; close it at the end.
+        listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(1)
+        port = listener.getsockname()[1]
+        try:
+            with tempfile.TemporaryDirectory() as tmp:
+                with mock.patch.dict(os.environ,
+                                     {"PAPERCLIP_HOME": tmp}, clear=False):
+                    # No pidfile written → pidfile branch skipped, falls
+                    # through to port scan.
+                    status = P.is_running(port=port)
+        finally:
+            listener.close()
+        self.assertTrue(status.running)
+        self.assertEqual(status.detection, "port-scan")
+        self.assertIsNone(status.pid)
+        self.assertEqual(status.port, port)
+
+    def test_url_field_returns_localhost_url_when_running(self):
+        """When running=True, status.url is http://localhost:<port>."""
+        # Use the pidfile path (cheapest, no socket needed).
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.dict(os.environ, {"PAPERCLIP_HOME": tmp}, clear=False):
+                run_dir = Path(tmp) / "run"
+                run_dir.mkdir(parents=True, exist_ok=True)
+                (run_dir / "dashboard.pid").write_text(f"{os.getpid()}\n")
+                status = P.is_running(port=8080)
+        self.assertTrue(status.running)
+        self.assertIsNotNone(status.url)
+        # Accept either localhost or 127.0.0.1 form so the implementation
+        # can pick whichever it prefers — the contract is "loopback URL".
+        self.assertIn(status.url, {
+            "http://localhost:8080",
+            "http://127.0.0.1:8080",
+        })
+
+
+if __name__ == "__main__":
+    unittest.main()