@clawpump/claw-agent 0.1.4 → 0.1.6

package/agent/hermes_cli/gateway_enroll.py

@@ -0,0 +1,250 @@
+"""``hermes gateway enroll`` — enroll a self-hosted gateway with a relay connector.
+
+The connector⇄gateway channel is authenticated (the gateway may be
+customer-managed and internet-exposed). This command is the gateway half of the
+zero-touch enrollment in the connector repo's
+``docs/connector-gateway-auth-design.md``:
+
+  1. Resolve a fresh Nous Portal access token from the existing login
+     (``~/.hermes/auth.json``) — the same path ``hermes dashboard register``
+     uses (``resolve_nous_access_token``). This proves *which Nous org (tenant)*
+     the caller owns; the connector derives the authoritative tenant from it via
+     ``GET /api/oauth/account`` (never from anything the gateway asserts).
+  2. POST ``{enrollmentToken, gatewayId}`` to the connector's ``/relay/enroll``
+     with that token in the ``Authorization`` header, over TLS.
+  3. The connector verifies the enrollment token (signature + single-use +
+     tenant match), mints a per-gateway secret, get-or-creates the per-tenant
+     delivery key, and returns both ONCE.
+  4. Persist ``GATEWAY_RELAY_ID`` / ``GATEWAY_RELAY_SECRET`` /
+     ``GATEWAY_RELAY_DELIVERY_KEY`` (+ ``GATEWAY_RELAY_URL`` if supplied) into
+     ``~/.hermes/.env``. The per-gateway secret authenticates the WS upgrade;
+     the per-tenant delivery key verifies signed inbound deliveries.
+
+Managed/hosted installs do NOT self-enroll: the orchestrator (NAS) mints the
+secret directly and stamps it into the container env, so this command refuses to
+run under ``is_managed()`` (mirrors ``dashboard register``).
+
+EXPERIMENTAL: the relay auth scheme may change without a deprecation cycle until
+≥2 Class-1 platforms validate the contract.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+import urllib.error
+import urllib.request
+from typing import Optional
+
+
+def _default_gateway_id() -> str:
+    """A stable-ish default gateway instance id: ``<hostname>-<pid-free slug>``.
+
+    The gatewayId identifies this enrolled instance for kill-switch granularity
+    (the connector indexes its secret verify list by it). Default to the host
+    name so a human can recognize it; overridable via ``--gateway-id``.
+    """
+    host = ""
+    try:
+        host = socket.gethostname().strip()
+    except Exception:
+        host = ""
+    return f"gw-{host or 'hermes'}"
+
+
+def _resolve_connector_url(override: Optional[str]) -> Optional[str]:
+    """Resolve the connector base URL (no trailing slash) for enrollment.
+
+    Precedence: explicit ``--connector-url`` flag > ``GATEWAY_RELAY_URL`` env >
+    ``gateway.relay_url`` in config.yaml. The relay URL is a ``ws(s)://`` dial
+    target; enrollment is an ``http(s)://`` POST to the same host, so we map the
+    scheme. Returns None when nothing is configured (the user must supply one).
+    """
+    raw = (override or os.environ.get("GATEWAY_RELAY_URL", "")).strip()
+    if not raw:
+        try:
+            from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+            cfg = (_load_gateway_config().get("gateway") or {})
+            raw = str(cfg.get("relay_url", "") or "").strip()
+        except Exception:
+            raw = ""
+    if not raw:
+        return None
+    raw = raw.rstrip("/")
+    # The relay dial URL is ws(s)://…/relay; enrollment posts to http(s)://…/relay/enroll.
+    if raw.startswith("ws://"):
+        raw = "http://" + raw[len("ws://"):]
+    elif raw.startswith("wss://"):
+        raw = "https://" + raw[len("wss://"):]
+    # Strip a trailing /relay path segment if the user pasted the dial URL.
+    if raw.endswith("/relay"):
+        raw = raw[: -len("/relay")]
+    return raw
+
+
+def _post_enroll(
+    *,
+    connector_base_url: str,
+    access_token: str,
+    enrollment_token: str,
+    gateway_id: str,
+    timeout: float = 15.0,
+) -> dict:
+    """POST to the connector's ``/relay/enroll`` and return the JSON body.
+
+    Raises RuntimeError with a user-facing message on any non-2xx / transport
+    failure. The connector returns ``{secret, deliveryKey, tenant, gatewayId}``
+    on success, ``{error}`` at 400/401/403.
+    """
+    url = f"{connector_base_url.rstrip('/')}/relay/enroll"
+    data = json.dumps({"enrollmentToken": enrollment_token, "gatewayId": gateway_id}).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = json.loads(resp.read().decode())
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        try:
+            detail = (json.loads(exc.read().decode()) or {}).get("error", "")
+        except Exception:
+            pass
+        if exc.code == 401:
+            raise RuntimeError(
+                "Connector rejected the caller identity (401). Your Nous Portal "
+                "token could not be verified — try `hermes auth login nous` and retry."
+            ) from exc
+        if exc.code == 403:
+            raise RuntimeError(
+                detail
+                or "Enrollment token invalid, expired, already used, or tenant mismatch (403)."
+            ) from exc
+        raise RuntimeError(
+            f"Connector returned HTTP {exc.code}" + (f": {detail}" if detail else "")
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(
+            f"Could not reach the connector at {connector_base_url}: {exc.reason}"
+        ) from exc
+
+    if not isinstance(payload, dict) or not payload.get("secret"):
+        raise RuntimeError("Connector returned an unexpected response (no secret).")
+    return payload
+
+
+def cmd_gateway_enroll(args) -> None:
+    """Enroll this gateway with a relay connector; persist the auth creds to .env."""
+    from hermes_cli.auth import AuthError, resolve_nous_access_token
+    from hermes_cli.config import is_managed, save_env_value
+
+    # Managed installs get GATEWAY_RELAY_* stamped in by the orchestrator (NAS
+    # mints the secret directly per the design's managed shape). Self-enrolling
+    # from inside such a container is a mistake — and save_env_value refuses to
+    # write anyway.
+    if is_managed():
+        print(
+            "✗ `hermes gateway enroll` is not available in a managed/hosted install.\n"
+            "  The relay gateway secret is provisioned by the hosting platform."
+        )
+        sys.exit(1)
+
+    enrollment_token = (getattr(args, "token", None) or os.environ.get("GATEWAY_RELAY_ENROLL_TOKEN", "")).strip()
+    if not enrollment_token:
+        print(
+            "✗ No enrollment token. Pass --token <token> (or set "
+            "GATEWAY_RELAY_ENROLL_TOKEN).\n"
+            "  The connector mints this single-use token when your tenant's route "
+            "is provisioned; it is delivered with your gateway config."
+        )
+        sys.exit(1)
+
+    connector_base_url = _resolve_connector_url(getattr(args, "connector_url", None))
+    if not connector_base_url:
+        print(
+            "✗ No connector URL. Pass --connector-url <url> (or set GATEWAY_RELAY_URL "
+            "/ gateway.relay_url in config.yaml)."
+        )
+        sys.exit(1)
+
+    gateway_id = (getattr(args, "gateway_id", None) or _default_gateway_id()).strip()
+
+    # 1. Resolve a fresh Nous access token (the tenant-proving identity).
+    try:
+        access_token = resolve_nous_access_token()
+    except AuthError as exc:
+        if getattr(exc, "relogin_required", False):
+            print("✗ You're not logged into Nous Portal.")
+            print("  Run `hermes setup` (or `hermes auth login nous`) first, then retry.")
+        else:
+            print(f"✗ Could not resolve a Nous Portal access token: {exc}")
+        sys.exit(1)
+    except Exception as exc:
+        print(f"✗ Could not resolve a Nous Portal access token: {exc}")
+        sys.exit(1)
+
+    # 2-3. Redeem the enrollment token at the connector.
+    try:
+        result = _post_enroll(
+            connector_base_url=connector_base_url,
+            access_token=access_token,
+            enrollment_token=enrollment_token,
+            gateway_id=gateway_id,
+        )
+    except RuntimeError as exc:
+        print(f"✗ Enrollment failed: {exc}")
+        sys.exit(1)
+
+    secret = str(result.get("secret") or "")
+    delivery_key = str(result.get("deliveryKey") or "")
+    tenant = str(result.get("tenant") or "")
+    resolved_gateway_id = str(result.get("gatewayId") or gateway_id)
+
+    # 4. Persist the creds idempotently. The secret + delivery key are sensitive;
+    #    save_env_value writes them to ~/.hermes/.env (0600 dir) and never logs.
+    to_write = {
+        "GATEWAY_RELAY_ID": resolved_gateway_id,
+        "GATEWAY_RELAY_SECRET": secret,
+        "GATEWAY_RELAY_DELIVERY_KEY": delivery_key,
+    }
+    # Persist the connector URL too (as the ws(s):// dial target) when supplied
+    # explicitly, so the runtime can dial without re-specifying it.
+    explicit_url = (getattr(args, "connector_url", None) or "").strip()
+    if explicit_url:
+        to_write["GATEWAY_RELAY_URL"] = explicit_url.rstrip("/")
+
+    for key, value in to_write.items():
+        if not value:
+            continue
+        try:
+            save_env_value(key, value)
+        except Exception as exc:
+            print(f"✗ Failed to write {key} to .env: {exc}")
+            sys.exit(1)
+
+    from hermes_cli.config import get_env_path
+
+    print(f'✓ Enrolled gateway "{resolved_gateway_id}"' + (f" for tenant {tenant}" if tenant else ""))
+    print()
+    print(f"  Wrote to {get_env_path()}:")
+    print(f"    GATEWAY_RELAY_ID={resolved_gateway_id}")
+    print("    GATEWAY_RELAY_SECRET=<hidden>")
+    print("    GATEWAY_RELAY_DELIVERY_KEY=<hidden>")
+    if explicit_url:
+        print(f"    GATEWAY_RELAY_URL={explicit_url.rstrip('/')}")
+    print()
+    print(
+        "  The gateway now authenticates its relay WS upgrade with the per-gateway\n"
+        "  secret and verifies signed inbound deliveries with the tenant delivery\n"
+        "  key. Restart the gateway to pick up the new env."
+    )

package/agent/hermes_cli/gateway_windows.py

@@ -29,6 +29,7 @@ Design notes
 from __future__ import annotations
 
 import ctypes
+import locale
 import os
 import re
 import shlex
@@ -52,6 +53,20 @@ _TASK_NAME_DEFAULT = "Hermes_Gateway"
 _TASK_DESCRIPTION = "Hermes Agent Gateway - Messaging Platform Integration"
 
 
+def _schtasks_encoding() -> str:
+    """Best-effort console encoding for decoding ``schtasks.exe`` output.
+
+    On localized Windows (e.g. Chinese), ``schtasks`` emits text in the OEM/ANSI
+    code page rather than UTF-8. Decoding with the wrong codec raised
+    ``UnicodeDecodeError`` inside ``subprocess``' reader threads. Prefer the
+    locale's preferred encoding and fall back to UTF-8.
+    """
+    try:
+        return locale.getpreferredencoding(False) or "utf-8"
+    except Exception:
+        return "utf-8"
+
+
 # ---------------------------------------------------------------------------
 # Platform guard
 # ---------------------------------------------------------------------------
@@ -112,6 +127,12 @@ def _exec_schtasks(args: list[str]) -> tuple[int, str, str]:
             [schtasks, *args],
             capture_output=True,
             text=True,
+            # Localized Windows emits schtasks output in the console code page,
+            # not UTF-8. Decode with the locale encoding and replace undecodable
+            # bytes so a non-UTF-8 status line never surfaces a UnicodeDecodeError
+            # traceback from subprocess' reader threads (issue #38172).
+            encoding=_schtasks_encoding(),
+            errors="replace",
             timeout=_SCHTASKS_TIMEOUT_S,
             # CREATE_NO_WINDOW avoids a flashing console window when the CLI
             # is itself hosted in a TUI. See tools/browser_tool.py for the
@@ -287,6 +308,29 @@ def get_startup_entry_path() -> Path:
     return _startup_dir() / f"{_sanitize_filename(get_task_name())}.cmd"
 
 
+# ---------------------------------------------------------------------------
+# Stable working directory
+# ---------------------------------------------------------------------------
+
+def _stable_gateway_working_dir(project_root: Path) -> str:
+    """Return a stable cwd for detached/startup gateway runs.
+
+    Mirror the POSIX service invariant: anchor at ``HERMES_HOME`` whenever it
+    exists so Scheduled Task / Startup launches do not fail at the ``cd`` step
+    after a transient checkout or worktree is moved away. Fall back to the
+    source checkout only if ``HERMES_HOME`` cannot be resolved yet.
+    """
+    from hermes_cli.config import get_hermes_home
+
+    try:
+        home = get_hermes_home()
+        if home and Path(home).is_dir():
+            return str(Path(home).resolve())
+    except Exception:
+        pass
+    return str(project_root)
+
+
 # ---------------------------------------------------------------------------
 # Script rendering
 # ---------------------------------------------------------------------------
@@ -300,7 +344,7 @@ def _build_gateway_cmd_script(
     """Build the ``gateway.cmd`` wrapper content (CRLF-terminated).
 
     The script:
-      - cd's into the project directory
+      - cd's into a stable working directory
       - exports HERMES_HOME, PYTHONIOENCODING, VIRTUAL_ENV
       - invokes ``pythonw -m hermes_cli.main [--profile X] gateway run``
         directly so the wrapper cmd.exe exits without a visible gateway console
@@ -336,13 +380,26 @@ def _build_gateway_cmd_script(
 
 
 def _build_startup_launcher(script_path: Path) -> str:
-    """The tiny .cmd that goes in the Startup folder. Just minimizes and chains."""
+    """The tiny .cmd that goes in the Startup folder. Just minimizes and chains.
+
+    Defense-in-depth: bail out silently if the target script is gone. Test
+    fixtures historically wrote Startup entries pointing at pytest tmp_path
+    directories that vanish after the test session. Without the existence
+    guard, every subsequent Windows login flashes a cmd.exe window that
+    fails to find the target. The check + ``exit /b 0`` keeps that case
+    silent.
+    """
+    quoted_target = _quote_cmd_script_arg(str(script_path))
     lines = [
         "@echo off",
         f"rem {_TASK_DESCRIPTION}",
+        # If the wrapper script is gone (typical for stale entries from
+        # uninstalled/migrated installs), silently no-op instead of
+        # flashing a cmd window with a "file not found" error.
+        f"if not exist {quoted_target} exit /b 0",
         # ``start "" /min`` detaches with a minimized console window.
         # ``/d /c`` on cmd.exe skips AUTORUN and runs the target script once.
-        f'start "" /min cmd.exe /d /c {_quote_cmd_script_arg(str(script_path))}',
+        f'start "" /min cmd.exe /d /c {quoted_target}',
     ]
     return "\r\n".join(lines) + "\r\n"
 
@@ -359,7 +416,7 @@ def _write_task_script() -> Path:
     )
 
     python_path = get_python_path()
-    working_dir = str(PROJECT_ROOT)
+    working_dir = _stable_gateway_working_dir(PROJECT_ROOT)
     hermes_home = str(Path(get_hermes_home()).resolve())
     profile_arg = _profile_arg(hermes_home)
 
@@ -434,6 +491,8 @@ def _install_scheduled_task(task_name: str, script_path: Path) -> tuple[bool, st
     return (False, f"schtasks /Create failed (code {last_code}): {last_err.strip()}")
 
 
+
+
 def _install_startup_entry(script_path: Path) -> Path:
     """Write the Startup-folder fallback launcher. Returns its path."""
     entry = get_startup_entry_path()
@@ -526,7 +585,8 @@ def _build_gateway_argv() -> tuple[list[str], str, dict[str, str]]:
     )
 
     python_exe, venv_dir, extra_pythonpath = _resolve_detached_python(get_python_path())
-    working_dir = str(PROJECT_ROOT)
+    project_root = str(PROJECT_ROOT)
+    working_dir = _stable_gateway_working_dir(PROJECT_ROOT)
     hermes_home = str(Path(get_hermes_home()).resolve())
     profile_arg = _profile_arg(hermes_home)
 
@@ -541,7 +601,7 @@ def _build_gateway_argv() -> tuple[list[str], str, dict[str, str]]:
         "HERMES_GATEWAY_DETACHED": "1",
         "VIRTUAL_ENV": str(venv_dir),
     }
-    _prepend_pythonpath(env_overlay, [working_dir, *extra_pythonpath] if extra_pythonpath else [])
+    _prepend_pythonpath(env_overlay, [project_root, *extra_pythonpath] if extra_pythonpath else [project_root])
     return argv, working_dir, env_overlay
 
 
@@ -881,7 +941,10 @@ def uninstall() -> None:
         else:
             print(f"⚠ schtasks /Delete returned code {code}: {detail}")
 
-    for path, label in [(startup_entry, "Windows login item"), (script_path, "Task script")]:
+    for path, label in [
+        (startup_entry, "Windows login item"),
+        (script_path, "Task script"),
+    ]:
         try:
             path.unlink()
             print(f"✓ Removed {label}: {path}")
@@ -939,6 +1002,139 @@ def _gateway_pids() -> list[int]:
     return list(find_gateway_pids())
 
 
+def _print_deep_probes() -> None:
+    """Print PASS/FAIL per individual probe of gateway liveness.
+
+    The default ``status`` output collapses several signals into one
+    ✓ / ✗ line, which is great when they agree and confusing when they
+    don't. The deep-probe block shows each underlying check independently
+    so the user can see exactly which signal is wrong.
+
+    Probes:
+      [1] PID file present
+      [2] Lock file present and held by some process
+      [3] gateway.status.get_running_pid() returns a PID
+      [4] _pid_exists(pid) — OS confirms the process is alive
+      [5] gateway_state.json exists and parses (and is fresh-ish)
+      [6] Last lifecycle event in gateway-exit-diag.log
+    """
+    import json
+    from datetime import datetime, timezone
+
+    from hermes_cli.config import get_hermes_home
+
+    home = Path(get_hermes_home()).resolve()
+    pid_path = home / "gateway.pid"
+    lock_path = home / "gateway.lock"
+    state_path = home / "gateway_state.json"
+    diag_path = home / "logs" / "gateway-exit-diag.log"
+
+    print()
+    print("Deep probes:")
+
+    def _mark(ok: bool) -> str:
+        return "PASS" if ok else "FAIL"
+
+    # [1] PID file
+    pid_exists = pid_path.exists()
+    pid_value: int | None = None
+    if pid_exists:
+        try:
+            data = json.loads(pid_path.read_text(encoding="utf-8"))
+            pid_value = int(data.get("pid")) if data.get("pid") is not None else None
+            print(f"  [1] {_mark(True):4s}  PID file present: {pid_path} (pid={pid_value})")
+        except Exception as exc:
+            print(f"  [1] {_mark(False):4s}  PID file present but unreadable: {exc}")
+    else:
+        print(f"  [1] {_mark(False):4s}  PID file missing: {pid_path}")
+
+    # [2] Lock file present + held
+    lock_held = False
+    lock_present = lock_path.exists()
+    if lock_present:
+        try:
+            from gateway.status import is_gateway_runtime_lock_active
+
+            lock_held = is_gateway_runtime_lock_active(lock_path)
+            print(f"  [2] {_mark(lock_held):4s}  Lock file held by a live process: {lock_path}")
+        except Exception as exc:
+            print(f"  [2] {_mark(False):4s}  Could not probe lock: {exc}")
+    else:
+        print(f"  [2] {_mark(False):4s}  Lock file missing: {lock_path}")
+
+    # [3] get_running_pid()
+    running_pid: int | None = None
+    try:
+        from gateway.status import get_running_pid
+
+        running_pid = get_running_pid(cleanup_stale=False)
+        print(f"  [3] {_mark(running_pid is not None):4s}  get_running_pid() => {running_pid}")
+    except Exception as exc:
+        print(f"  [3] {_mark(False):4s}  get_running_pid() raised: {exc!r}")
+
+    # [4] _pid_exists() on the probed PID
+    candidate_pid = running_pid if running_pid is not None else pid_value
+    if candidate_pid is not None:
+        try:
+            from gateway.status import _pid_exists
+
+            alive = bool(_pid_exists(candidate_pid))
+            print(f"  [4] {_mark(alive):4s}  _pid_exists({candidate_pid}) => {alive}")
+        except Exception as exc:
+            print(f"  [4] {_mark(False):4s}  _pid_exists raised: {exc!r}")
+    else:
+        print(f"  [4] {_mark(False):4s}  No candidate PID to verify")
+
+    # [5] runtime status file
+    if state_path.exists():
+        try:
+            state_data = json.loads(state_path.read_text(encoding="utf-8"))
+            gateway_state = state_data.get("gateway_state")
+            updated_at = state_data.get("updated_at")
+            age_str = ""
+            if updated_at:
+                try:
+                    updated_dt = datetime.fromisoformat(updated_at.replace("Z", "+00:00"))
+                    now = datetime.now(timezone.utc)
+                    age_seconds = int((now - updated_dt).total_seconds())
+                    age_str = f" (updated {age_seconds}s ago)"
+                except Exception:
+                    pass
+            ok = gateway_state == "running"
+            print(f"  [5] {_mark(ok):4s}  gateway_state.json state={gateway_state!r}{age_str}")
+        except Exception as exc:
+            print(f"  [5] {_mark(False):4s}  gateway_state.json present but unreadable: {exc}")
+    else:
+        print(f"  [5] {_mark(False):4s}  gateway_state.json missing: {state_path}")
+
+    # [6] Last lifecycle event from the exit-diag log
+    if diag_path.exists():
+        try:
+            with open(diag_path, "rb") as fh:
+                # Read last ~4KB; one event is well under 500 bytes.
+                fh.seek(0, 2)
+                size = fh.tell()
+                fh.seek(max(0, size - 4096))
+                tail = fh.read().decode("utf-8", errors="replace").splitlines()
+            last_event = next((ln for ln in reversed(tail) if ln.strip()), "")
+            if last_event:
+                try:
+                    event = json.loads(last_event)
+                    tag = event.get("tag", "?")
+                    pid = event.get("pid", "?")
+                    ts = event.get("ts", "?")
+                    healthy = tag in ("gateway.start",)
+                    print(f"  [6] {_mark(healthy):4s}  Last lifecycle event: tag={tag} pid={pid} ts={ts}")
+                except Exception:
+                    print(f"  [6] {_mark(False):4s}  Last lifecycle line not JSON: {last_event[:120]}")
+            else:
+                print(f"  [6] {_mark(False):4s}  exit-diag log empty: {diag_path}")
+        except Exception as exc:
+            print(f"  [6] {_mark(False):4s}  exit-diag log unreadable: {exc}")
+    else:
+        print(f"  [6] {_mark(False):4s}  exit-diag log missing: {diag_path}")
+
+
 def status(deep: bool = False) -> None:
     """Print a status report for the Windows gateway service."""
     _assert_windows()
@@ -966,9 +1162,12 @@ def status(deep: bool = False) -> None:
 
     if deep:
         print()
-        print(f"  Task name:     {task_name}")
-        print(f"  Task script:   {get_task_script_path()}")
-        print(f"  Startup entry: {get_startup_entry_path()}")
+        print(f"  Task name:        {task_name}")
+        print(f"  Task script:      {get_task_script_path()}")
+        print(f"  Startup entry:    {get_startup_entry_path()}")
+        # Surface the per-probe truth so the user can see *which* signal
+        # is lying when the high-level summary disagrees with reality.
+        _print_deep_probes()
 
     if not task_installed and not startup_installed and not pids:
         print()
@@ -1103,10 +1302,54 @@ def stop() -> None:
         print("✗ No gateway was running")
 
 
+def _wait_for_gateway_absent(timeout_s: float = 30.0, interval_s: float = 0.5) -> bool:
+    """Block until no gateway process is detectable, or the timeout elapses.
+
+    ``stop()`` can return while the previous gateway is still draining
+    in-flight agents (the drain runs up to the restart-drain timeout). Uses the
+    authoritative ``get_running_pid()`` (lock + liveness + start-time +
+    gateway-shape) plus the now-strict ``_gateway_pids()`` scan so a relaunch
+    never races a still-alive old process.
+    """
+    from gateway.status import get_running_pid
+
+    deadline = time.monotonic() + max(timeout_s, interval_s)
+    while time.monotonic() < deadline:
+        if get_running_pid() is None and not _gateway_pids():
+            return True
+        time.sleep(interval_s)
+    return get_running_pid() is None and not _gateway_pids()
+
+
 def restart() -> None:
-    """Stop the gateway then start it again."""
+    """Stop the gateway then start it again.
+
+    Waits for the old gateway to be authoritatively gone before relaunching --
+    otherwise ``start()``'s "already running" guard sees the still-draining old
+    process and no-ops, and when that process later exits nothing replaces it (a
+    silent outage). Fails loudly if the process can't be cleared or the relaunch
+    doesn't produce a running gateway.
+    """
     _assert_windows()
+    from hermes_cli.gateway import kill_gateway_processes
+
     stop()
+
+    if not _wait_for_gateway_absent(timeout_s=30.0):
+        print("⚠ Gateway still present after stop; forcing termination before restart...")
+        kill_gateway_processes(all_profiles=False, force=True)
+        if not _wait_for_gateway_absent(timeout_s=10.0):
+            raise RuntimeError(
+                "Gateway process still detected after force kill; refusing to "
+                "start a duplicate. Investigate stray PIDs before retrying."
+            )
+
     # Give Windows a moment to release the listening port.
     time.sleep(1.0)
     start()
+
+    if not _wait_for_gateway_ready(timeout_s=15.0):
+        raise RuntimeError(
+            "Gateway restart did not produce a running gateway process. "
+            "Check logs/gateway.log and run `hermes gateway status`."
+        )