standkit 0.6.0__tar.gz → 0.6.1__tar.gz

{standkit-0.6.0 → standkit-0.6.1}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 standkit contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 standkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{standkit-0.6.0/standkit.egg-info → standkit-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: standkit
-Version: 0.6.0
+Version: 0.6.1
 Summary: Свободное ядро (MIT) для управления жизненным циклом локальных и удалённых стендов BPMSoft: headless start/stop/restart, health-пробы, логи, реестр стендов. Часть экосистемы BPMkit.
 Author: standkit contributors
 License-Expression: MIT

{standkit-0.6.0 → standkit-0.6.1}/docs/BACKLOG.md

@@ -61,6 +61,8 @@ TCP-порту** — их достаточно для дашборда.
 | Ярлык на рабочем столе для **macOS** | осознанно не реализовано — возвращается понятный статус | `standkit_hub/shortcut.py` (докстринг) |
 | Нативный трей (иконка со сводным состоянием, баллоны при падении) | не реализовано — потребовало бы `pystray`/`Pillow` против инварианта stdlib-only. Вместо него PWA-установка и компактный режим `?view=compact` | `standkit_hub/web/manifest.webmanifest` |
 | Автозапуск хаба при входе в систему | не реализовано; механика ярлыка есть | `standkit_hub/shortcut.py` |
+| Остановка хаба, когда дашборд никто не смотрит (idle-shutdown / heartbeat от фронта) | не реализовано — запущенный ярлыком процесс живёт под `pythonw` без окна до перезагрузки или ручного снятия. Дубли при повторном клике по ярлыку закрыты single-instance проверкой, но сам «вечный» процесс остаётся | `standkit_hub/__main__.py` (`serve_forever` без таймаута), `standkit_hub/server.py::probe_hub_instance` |
+| Остановка хаба из интерфейса (кнопка «Завершить работу диспетчера») | не реализовано — единственный штатный способ Ctrl+C недоступен при запуске ярлыком (консоли нет) | `standkit_hub/__main__.py` (обработка `KeyboardInterrupt`) |
 
 ## Секреты
 

{standkit-0.6.0 → standkit-0.6.1}/docs/CHANGELOG.md

@@ -3,6 +3,27 @@
 Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/); версии —
 [SemVer](https://semver.org/lang/ru/). Даты — 2026 год.
 
+## [0.6.1] — 2026-07-27
+
+### Исправлено
+- **Повторный запуск по ярлыку больше не поднимает второй диспетчер.** Ярлык
+  стартует хаб через `pythonw.exe`, окна нет, а закрытие браузера процесс не
+  останавливает — idle-shutdown у хаба нет. Поэтому второй клик по ярлыку
+  запускал ещё один экземпляр: два фоновых поллера дёргали health-пробы и
+  внешние команды бэкендов хостинга над одним `projects.json`, а окно
+  открывалось на другом origin со своей копией localStorage (сбрасывалась
+  тема). На Windows было хуже, чем предполагалось: из-за `SO_REUSEADDR` bind
+  на уже слушаемый 8770 проходил успешно, и два хаба молча делили один порт.
+  Теперь перед стартом проверяется, не работает ли диспетчер уже — если да,
+  просто открывается браузер на нём. Откат на свободный порт сохранён для
+  случая, когда 8770 занял чужой сервис.
+- **Дашборд честно сообщает, что диспетчер остановлен.** Раньше вкладка с
+  умершим хабом продолжала показывать последний снапшот как живой, а
+  единственными признаками были красная точка в углу и браузерное
+  `Failed to fetch` в тостах. Теперь показывается баннер с объяснением и тем,
+  что делать, устаревшая таблица гасится, а сетевые ошибки и 401 («сессия не
+  подтверждена» после перезапуска диспетчера) переведены на понятный язык.
+
 ## [0.6.0] — 2026-07-27
 
 ### Добавлено
@@ -104,6 +125,7 @@
 - Первый публичный релиз ядра `standkit` + агента `standkit_agent` + веб-дашборда
   `standkit_hub` на PyPI; фронт-README, `docs/REMOTE_STANDS.md`, скриншоты.
 
+[0.6.1]: https://pypi.org/project/standkit/0.6.1/
 [0.6.0]: https://pypi.org/project/standkit/0.6.0/
 [0.5.2]: https://pypi.org/project/standkit/0.5.2/
 [0.5.1]: https://pypi.org/project/standkit/0.5.1/

{standkit-0.6.0 → standkit-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "standkit"
-version = "0.6.0"
+version = "0.6.1"
 description = "Свободное ядро (MIT) для управления жизненным циклом локальных и удалённых стендов BPMSoft: headless start/stop/restart, health-пробы, логи, реестр стендов. Часть экосистемы BPMkit."
 readme = "README.md"
 license = "MIT"

{standkit-0.6.0 → standkit-0.6.1}/standkit/__init__.py

@@ -6,6 +6,6 @@ standkit — свободное (MIT) ядро управления жизнен
 и docs/ARCHITECTURE.md в корне репозитория.
 """
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 __all__ = ["__version__"]

{standkit-0.6.0 → standkit-0.6.1/standkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: standkit
-Version: 0.6.0
+Version: 0.6.1
 Summary: Свободное ядро (MIT) для управления жизненным циклом локальных и удалённых стендов BPMSoft: headless start/stop/restart, health-пробы, логи, реестр стендов. Часть экосистемы BPMkit.
 Author: standkit contributors
 License-Expression: MIT

{standkit-0.6.0 → standkit-0.6.1}/standkit.egg-info/SOURCES.txt

@@ -70,6 +70,7 @@ tests/test_hub_redis_min.py
 tests/test_hub_register.py
 tests/test_hub_server.py
 tests/test_hub_shortcut.py
+tests/test_hub_single_instance.py
 tests/test_lifecycle.py
 tests/test_logs.py
 tests/test_models.py

{standkit-0.6.0 → standkit-0.6.1}/standkit_agent/__init__.py

@@ -1,9 +1,9 @@
-"""
-standkit_agent — лёгкий headless-демон на хосте стенда: ядро standkit +
-крошечный HTTP/RPC сервер (stdlib-only: http.server, subprocess, socket,
-urllib). Кроссплатформенный (Windows/Linux). Без Qt и без сторонних
-зависимостей — специально, чтобы агент можно было развернуть на "голом"
-хосте стенда без сборки колёс под конкретную ОС/архитектуру.
-"""
-
-__all__: list[str] = []
+"""
+standkit_agent — лёгкий headless-демон на хосте стенда: ядро standkit +
+крошечный HTTP/RPC сервер (stdlib-only: http.server, subprocess, socket,
+urllib). Кроссплатформенный (Windows/Linux). Без Qt и без сторонних
+зависимостей — специально, чтобы агент можно было развернуть на "голом"
+хосте стенда без сборки колёс под конкретную ОС/архитектуру.
+"""
+
+__all__: list[str] = []

{standkit-0.6.0 → standkit-0.6.1}/standkit_agent/audit.py

@@ -1,93 +1,93 @@
-"""
-Структурный append-only аудит-лог агента (JSON-lines) — обязателен для
-DevSecOps-эксплуатации headless-агента, управляющего процессами на хосте
-стенда.
-
-Формат одной строки (JSON-объект, без вложенных переводов строк):
-    {
-      "ts": "2026-07-23T12:34:56.789012+00:00",   # UTC ISO-8601
-      "src_ip": "10.0.0.5",
-      "identity": "control",                       # control|readonly|<CN>|"-"
-      "method": "POST",
-      "path": "/stand/demo/restart",
-      "action": "restart",
-      "result": "ok",                               # ok|denied|error
-      "code": 200
-    }
-
-Секреты/токены НИКОГДА не попадают в аудит-запись — только идентичность
-уровня "какой скоуп/CN использован", не сам токен.
-
-STDLIB-ONLY: используется ``logging`` с отдельным именованным логгером и
-файловым хендлером (не корневой логгер — чтобы не смешиваться с чужой
-конфигурацией логирования встраивающего процесса).
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Optional
-
-DEFAULT_AUDIT_LOG_PATH = Path.home() / ".standkit" / "audit.log"
-
-_LOGGER_NAME = "standkit_agent.audit"
-
-
-def build_audit_logger(path: Optional[Path] = None) -> logging.Logger:
-    """
-    Возвращает (создавая при необходимости) файловый логгер аудита.
-
-    Идемпотентно: повторный вызов с тем же путём не плодит дублирующиеся
-    хендлеры (полезно в тестах, где ``run_server``/фабрики обработчика могут
-    вызываться многократно в одном процессе).
-    """
-    p = Path(path) if path else DEFAULT_AUDIT_LOG_PATH
-    p.parent.mkdir(parents=True, exist_ok=True)
-
-    logger_name = f"{_LOGGER_NAME}.{abs(hash(str(p.resolve())))}"
-    logger = logging.getLogger(logger_name)
-    logger.setLevel(logging.INFO)
-    logger.propagate = False  # не утекает в root-логгер встраивающего процесса
-
-    already_attached = any(
-        isinstance(h, logging.FileHandler) and Path(h.baseFilename) == p.resolve()
-        for h in logger.handlers
-    )
-    if not already_attached:
-        handler = logging.FileHandler(p, encoding="utf-8")
-        handler.setFormatter(logging.Formatter("%(message)s"))
-        logger.addHandler(handler)
-    return logger
-
-
-def audit_event(
-    logger: logging.Logger,
-    *,
-    src_ip: str,
-    identity: str,
-    method: str,
-    path: str,
-    action: str,
-    result: str,
-    code: int,
-) -> None:
-    """Пишет одну JSON-строку аудита. Никогда не бросает исключений наружу."""
-    entry = {
-        "ts": datetime.now(timezone.utc).isoformat(),
-        "src_ip": src_ip,
-        "identity": identity or "-",
-        "method": method,
-        "path": path,
-        "action": action,
-        "result": result,
-        "code": code,
-    }
-    try:
-        logger.info(json.dumps(entry, ensure_ascii=False))
-    except Exception:
-        # Аудит-лог не должен ронять обработку запроса ни при каких
-        # обстоятельствах (диск полон, права на файл и т.п.).
-        pass
+"""
+Структурный append-only аудит-лог агента (JSON-lines) — обязателен для
+DevSecOps-эксплуатации headless-агента, управляющего процессами на хосте
+стенда.
+
+Формат одной строки (JSON-объект, без вложенных переводов строк):
+    {
+      "ts": "2026-07-23T12:34:56.789012+00:00",   # UTC ISO-8601
+      "src_ip": "10.0.0.5",
+      "identity": "control",                       # control|readonly|<CN>|"-"
+      "method": "POST",
+      "path": "/stand/demo/restart",
+      "action": "restart",
+      "result": "ok",                               # ok|denied|error
+      "code": 200
+    }
+
+Секреты/токены НИКОГДА не попадают в аудит-запись — только идентичность
+уровня "какой скоуп/CN использован", не сам токен.
+
+STDLIB-ONLY: используется ``logging`` с отдельным именованным логгером и
+файловым хендлером (не корневой логгер — чтобы не смешиваться с чужой
+конфигурацией логирования встраивающего процесса).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_AUDIT_LOG_PATH = Path.home() / ".standkit" / "audit.log"
+
+_LOGGER_NAME = "standkit_agent.audit"
+
+
+def build_audit_logger(path: Optional[Path] = None) -> logging.Logger:
+    """
+    Возвращает (создавая при необходимости) файловый логгер аудита.
+
+    Идемпотентно: повторный вызов с тем же путём не плодит дублирующиеся
+    хендлеры (полезно в тестах, где ``run_server``/фабрики обработчика могут
+    вызываться многократно в одном процессе).
+    """
+    p = Path(path) if path else DEFAULT_AUDIT_LOG_PATH
+    p.parent.mkdir(parents=True, exist_ok=True)
+
+    logger_name = f"{_LOGGER_NAME}.{abs(hash(str(p.resolve())))}"
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False  # не утекает в root-логгер встраивающего процесса
+
+    already_attached = any(
+        isinstance(h, logging.FileHandler) and Path(h.baseFilename) == p.resolve()
+        for h in logger.handlers
+    )
+    if not already_attached:
+        handler = logging.FileHandler(p, encoding="utf-8")
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        logger.addHandler(handler)
+    return logger
+
+
+def audit_event(
+    logger: logging.Logger,
+    *,
+    src_ip: str,
+    identity: str,
+    method: str,
+    path: str,
+    action: str,
+    result: str,
+    code: int,
+) -> None:
+    """Пишет одну JSON-строку аудита. Никогда не бросает исключений наружу."""
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "src_ip": src_ip,
+        "identity": identity or "-",
+        "method": method,
+        "path": path,
+        "action": action,
+        "result": result,
+        "code": code,
+    }
+    try:
+        logger.info(json.dumps(entry, ensure_ascii=False))
+    except Exception:
+        # Аудит-лог не должен ронять обработку запроса ни при каких
+        # обстоятельствах (диск полон, права на файл и т.п.).
+        pass

{standkit-0.6.0 → standkit-0.6.1}/standkit_hub/__main__.py

@@ -8,7 +8,10 @@
 (схема+хост+ПОРТ) является ключом браузерного localStorage и HTTP-кэша, и на
 прежнем эфемерном порту каждый запуск давал новый origin — тема не
 запоминалась, кэш статики был вечно холодным, закладка протухала. Если порт
-занят, хаб не падает, а откатывается на эфемерный и честно об этом пишет
+занят, хаб не падает: сначала проверяет, не занял ли его НАШ ЖЕ работающий
+экземпляр (single-instance, см. ``server.probe_hub_instance``) — тогда просто
+открывает браузер на нём и выходит, не плодя второй фоновый поллер; если порт
+занял чужой сервис — откатывается на эфемерный и честно об этом пишет
 (``--port 0`` — явная просьба эфемерного порта). Флаг
 ``--desktop`` — опциональная нативная оболочка через ``pywebview`` (extra
 ``standkit[desktop]``); при отсутствии пакета хаб печатает понятное
@@ -30,7 +33,7 @@ from pathlib import Path
 
 from standkit_hub.config import HubConfig
 from standkit_hub.security import InsecureBindError, generate_session_token
-from standkit_hub.server import DEFAULT_HUB_PORT, bind_hub_server
+from standkit_hub.server import DEFAULT_HUB_PORT, HubAlreadyRunning, bind_hub_server
 from standkit_hub.shortcut import install_desktop_shortcut, uninstall_desktop_shortcut
 
 
@@ -114,6 +117,22 @@ def main(argv: list[str] | None = None) -> int:
             insecure=args.insecure,
             on_fallback=_report_port_busy,
         )
+    except HubAlreadyRunning as exc:
+        # Второй запуск по ярлыку (обычный сценарий: окно браузера закрыли, а
+        # процесс под pythonw остался жить — idle-shutdown у хаба нет). Второй
+        # сервер здесь не нужен и вреден: два фоновых поллера над одним
+        # реестром плюс разъехавшийся localStorage на другом origin. Просто
+        # открываем браузер на уже работающем экземпляре.
+        #
+        # Токен в URL НЕ подставляем — у нас его нет (он сгенерирован в чужом
+        # процессе). Работающий экземпляр узнает браузер по сессионной cookie,
+        # выданной при первом открытии; если cookie не пережила полное
+        # закрытие браузера, дашборд честно скажет об этом (см. app.js,
+        # разбор 401), и достаточно перезапустить диспетчер.
+        print(f"[standkit-hub] диспетчер уже работает на {exc.host}:{exc.port} — открываю его, второй не запускаю")
+        if not args.no_browser:
+            webbrowser.open(exc.url)
+        return 0
     except InsecureBindError as exc:
         print(f"[standkit-hub] {exc}", file=sys.stderr)
         return 1

{standkit-0.6.0 → standkit-0.6.1}/standkit_hub/server.py

@@ -86,6 +86,10 @@ from standkit_hub.shortcut import install_desktop_shortcut, uninstall_desktop_sh
 # см. ``bind_hub_server``: откат на эфемерный с явным сообщением, а не падение.
 DEFAULT_HUB_PORT = 8770
 
+# Заголовок-опознаватель хаба, который ставится на КАЖДЫЙ ответ (см.
+# ``Handler.end_headers``) и читается ``probe_hub_instance``.
+HUB_IDENTITY_HEADER = "X-Standkit-Hub"
+
 _STAND_ACTION_RE = re.compile(
     r"^/api/stand/(?P<name>[^/]+)/(?P<action>status|logs|start|stop|restart|adopt|state|redis-clear)$"
 )
@@ -553,6 +557,17 @@ def make_handler(
             # чтобы не шуметь секретными путями (/api/secret/<ref>) в консоли.
             pass
 
+        def end_headers(self) -> None:
+            # Метка «здесь живой standkit-hub» на КАЖДОМ ответе, включая 401 и
+            # 404. Нужна single-instance проверке (см. probe_hub_instance):
+            # второй запуск по ярлыку должен отличить свой уже работающий
+            # экземпляр от чужого сервиса, занявшего порт, НЕ предъявляя
+            # токена — а значит, судить можно только по неаутентифицированному
+            # ответу. Версия в значении — диагностика, не контракт: сравнивать
+            # её не нужно, важен сам факт заголовка.
+            self.send_header(HUB_IDENTITY_HEADER, _standkit_version)
+            super().end_headers()
+
         def _send_json(self, code: int, payload: dict) -> None:
             body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
             self.send_response(code)
@@ -1713,6 +1728,73 @@ def create_hub_server(
 _PORT_BUSY_ERRNOS = frozenset({errno.EADDRINUSE, errno.EACCES})
 
 
+def probe_hub_instance(host: str, port: int, *, timeout: float = 1.5) -> Optional[str]:
+    """
+    Отвечает ли на ``host:port`` уже работающий standkit-hub?
+
+    Возвращает строку версии из заголовка ``X-Standkit-Hub`` либо ``None``,
+    если порт занят чем-то другим (или не отвечает вовремя).
+
+    ЗАЧЕМ. Ярлык на рабочем столе запускает хаб через ``pythonw.exe`` — без
+    консоли. Закрытие окна браузера НЕ останавливает процесс (сервер живёт в
+    ``serve_forever``, idle-shutdown нет), поэтому повторный клик по ярлыку
+    раньше поднимал ВТОРОЙ экземпляр: порт 8770 занят → откат на эфемерный →
+    два фоновых поллера дёргают health-пробы и ``subprocess`` бэкендов
+    хостинга над одним ``projects.json``, а origin у второго окна другой, то
+    есть своя копия localStorage. Сообщение об откате уходило в ``stderr``,
+    которого при ``pythonw`` никто не видит.
+
+    Запрос НАМЕРЕННО неаутентифицированный: сессионного токена работающего
+    экземпляра у нас нет и быть не может. Поэтому опознание идёт по
+    заголовку, который хаб ставит на любой ответ, включая 401 — отдавать
+    токен или иную чувствительную информацию в обмен на «постучались с
+    loopback» нельзя, это был бы обход аутентификации.
+
+    Сетевые ошибки здесь не исключение, а нормальный ответ «не хаб»: чужой
+    сервис может рвать соединение, отвечать мусором или молчать. Любой сбой
+    трактуем консервативно — ``None``, то есть «не наш», и вызывающий уходит
+    в прежний откат на эфемерный порт.
+    """
+    import http.client
+
+    conn = None
+    try:
+        conn = http.client.HTTPConnection(host, port, timeout=timeout)
+        # HEAD, а не GET: опознавательный заголовок есть и здесь, а тело
+        # (index.html целиком) читать незачем.
+        conn.request("HEAD", "/")
+        resp = conn.getresponse()
+        value = resp.getheader(HUB_IDENTITY_HEADER)
+        return value or None
+    except Exception:
+        return None
+    finally:
+        if conn is not None:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+
+class HubAlreadyRunning(RuntimeError):
+    """
+    На запрошенном порту уже работает standkit-hub.
+
+    Не ошибка в привычном смысле, а сигнал вызывающему (CLI): второй процесс
+    поднимать не нужно, надо открыть браузер на уже работающем экземпляре.
+    """
+
+    def __init__(self, host: str, port: int, version: Optional[str] = None) -> None:
+        self.host = host
+        self.port = port
+        self.version = version
+        super().__init__(f"диспетчер уже работает на {host}:{port}")
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}/"
+
+
 def bind_hub_server(
     host: str,
     port: int,
@@ -1723,6 +1805,7 @@ def bind_hub_server(
     insecure: bool = False,
     poll: bool = True,
     on_fallback: Optional[Callable[[int, OSError], None]] = None,
+    single_instance: bool = True,
 ) -> HubHTTPServer:
     """
     ``create_hub_server`` + откат на эфемерный порт, если запрошенный занят.
@@ -1737,7 +1820,29 @@ def bind_hub_server(
     ``on_fallback(requested_port, exc)`` вызывается ПЕРЕД повторным bind'ом,
     чтобы вызывающий (CLI) мог сообщить пользователю причину. Ошибки, не
     связанные с занятостью порта, пробрасываются как есть — «честный отказ».
+
+    ``single_instance=True`` (по умолчанию): перед bind'ом проверяем, не занял
+    ли порт НАШ ЖЕ работающий хаб (см. ``probe_hub_instance``) — если да,
+    второй экземпляр не поднимается, бросается ``HubAlreadyRunning``, и CLI
+    просто открывает браузер на уже работающем. Откат на эфемерный остаётся
+    для случая «порт занял чужой сервис»: тогда второй хаб действительно нужен.
+    ``single_instance=False`` возвращает прежнее безусловное поведение и
+    нужен тестам, которым надо поднять два хаба подряд.
     """
+    # Проверка ДО bind'а, а не в обработчике OSError — и это принципиально.
+    # ``ThreadingHTTPServer.allow_reuse_address = 1`` (SO_REUSEADDR), а на
+    # Windows SO_REUSEADDR разрешает второму процессу занять УЖЕ слушаемый
+    # порт: bind проходит успешно, EADDRINUSE не возникает, и два хаба
+    # оказываются на одном 8770 — входящие соединения распределяются между
+    # ними непредсказуемо. То есть на Windows отката на эфемерный порт даже не
+    # случалось, было тихое раздвоение (обнаружено тестом
+    # tests/test_hub_single_instance.py). Единственный переносимый способ
+    # узнать правду — постучаться и посмотреть, кто ответит.
+    if single_instance and port != 0:
+        running = probe_hub_instance(host, port)
+        if running is not None:
+            raise HubAlreadyRunning(host, port, running)
+
     try:
         return create_hub_server(
             host,