standkit 0.12.1__tar.gz → 0.12.2__tar.gz

{standkit-0.12.1/standkit.egg-info → standkit-0.12.2}/PKG-INFO

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

{standkit-0.12.1 → standkit-0.12.2}/docs/CHANGELOG.md

@@ -5,6 +5,60 @@
 
 ## [Unreleased]
 
+## [0.12.2] — 2026-09-19
+
+### Исправлено
+
+- **Диспетчер выходил по простою при ЖИВЫХ стендах (GAP-383).** Живой инцидент
+  владельца 18.09.2026 20:56: хаб завершился штатно (`request_self_shutdown`),
+  три работающих стенда остались без управления, на экране была только ошибка
+  связи. Предикат простоя `_IdleShutdownWatcher.has_running_stands()` сравнивал
+  `process.state` со строкой `"running"`, **которой в `ProbeState` нет вообще**
+  (`ok`/`down`/`unknown`/`skipped`) — то есть на любом реальном снапшоте он
+  отвечал «стендов нет», и 30-минутный таймер срабатывал независимо от того,
+  сколько стендов работает. Набор тестов оставался зелёным, потому что его
+  двойник снапшота подставлял то самое выдуманное `"running"`; теперь двойник
+  повторяет поля настоящего `StatusSnapshot`, а отдельный тест-сторож следит,
+  что значения `"running"` в `ProbeState` по-прежнему нет.
+  Тем же гэпом закрыты два способа принять незнание за пустоту: снапшот-ОТКАЗ
+  поллера (`_safe_build`: `stands=[]`, `probed=False`, `error=...`) и
+  непробованный слепок реестра (`probed=False`, состояния `pending`) теперь
+  трактуются как «стенды есть» — ровно как обещали докстринг предиката и
+  ADR-0007 («незнание = остаёмся»).
+- **Автовыход при заменённых под живым процессом файлах пакета (GAP-383).**
+  `pip install standkit` поверх работающего диспетчера (владелец сделал это за
+  два часа до инцидента) оставляет на диске новый код, а в памяти старый.
+  Детект рассинхрона у хаба был (ADR-0007 §4), но автовыход про него не знал.
+  Теперь при расхождении версии «с диска» и «из памяти» диспетчер **не
+  выходит** по простою: перезапуск остаётся действием человека
+  (`POST /api/hub/restart` с открытой страницы), молчаливого самоперезапуска
+  фонового процесса не вводится. Ошибка чтения версии — тихий фолбэк, она не
+  объявляет рассинхрон и не запрещает автовыход навсегда.
+- **Усыновлённые и поднятые мимо диспетчера стенды считаются живыми
+  (GAP-385).** Условие простоя теперь «нет НИ ОДНОГО стенда, живого ПО ФАКТУ
+  пробы (`ProbeState.OK`, то есть по порту/pid)», а не «нет запущенных нами».
+  Стенд с мёртвым родителем (`standkit.adopt`, бейдж `process.external`) —
+  такой же повод остаться: потерять управление им ничуть не лучше, чем своим.
+
+### Добавлено
+
+- **Лог диспетчера в файл (GAP-384).** Новый модуль `standkit_hub/hub_logging.py`:
+  `resolve_log_dir()` (`%LOCALAPPDATA%\BPMkit\logs\hub.log`, на POSIX —
+  `$XDG_STATE_HOME`/`~/.local/state`) и ротация 2 МБ × 5. Причина слепоты при
+  разборе инцидента была структурной: ярлык запускает диспетчер через
+  `pythonw.exe`, у которого `sys.stderr` не подключён никуда (и может быть
+  `None`), а все объяснения — «простой N минут», «стоп-запрос», «перехват
+  порта» — писались через `print(..., file=sys.stderr)` и существовали ровно
+  на время своего вывода. Теперь в файл пишутся: старт и версия, запрос
+  штатного выхода, стоп-запрос (включая протухший) и **факты, по которым
+  принято решение об автовыходе** — `sse_client_count`, `has_running_stands`,
+  `snapshot_probed`, `snapshot_error`; отказ фонового опроса
+  (`poller._safe_build`) логируется с трейсбеком; необработанное исключение
+  процесса уходит в лог через `sys.excepthook`. Все 16 `print(..., file=sys.stderr)`
+  в `standkit_hub/__main__.py` переведены на `logging`. Неудача настройки лога
+  старт НЕ прерывает: диспетчер без лога хуже, но несравнимо лучше
+  незапустившегося.
+
 ## [0.12.1] — 2026-09-17
 
 ### Добавлено

{standkit-0.12.1 → standkit-0.12.2}/docs/adr/0007-hub-exit-idle-and-plain-restart.md

@@ -1,7 +1,8 @@
 # ADR-0007 — Выход из диспетчера, автовыход по простою и перезапуск без повышения прав
 
 - Статус: **Принято / реализовано** (v0.12.0, 17.09.2026; постановка владельца Д-3 и
-  GAP-276 dev-репо BPMkit).
+  GAP-276 dev-репо BPMkit). **Уточнено v0.12.2 (19.09.2026) по живому инциденту
+  18.09.2026 20:56** — GAP-383/384/385, см. раздел «Уточнение 19.09.2026» ниже.
 - Контекст-владелец: Владимир Терновский
 - Связано: [ADR-0006](0006-hub-elevated-restart.md) (перезапуск через UAC — вся машинерия
   перезапуска переиспользуется здесь), GAP-229/GAP-284 (именованный мьютекс для
@@ -61,8 +62,8 @@
 
 | | вкладка открыта | вкладка закрыта |
 |---|---|---|
-| **есть running-стенды** | работаем | работаем |
-| **нет running-стендов** | работаем | **простой** |
+| **есть живые стенды** (`ProbeState.OK` по порту/pid) | работаем | работаем |
+| **нет живых стендов** | работаем | **простой** |
 
 Почему И, а не ИЛИ. Закрытая вкладка при живых стендах — штатная работа: стенды подняли
 через диспетчер и ушли ими пользоваться; выйти сейчас значит потерять над ними управление
@@ -74,9 +75,11 @@
 время последнего запроса: SSE держится ровно пока страница открыта, и это единственный
 сигнал, который не приходится угадывать по таймерам опроса.
 
-**Незнание трактуется в пользу «остаться»**: поллера нет или он ещё не отдал первый
-снапшот — считаем, что стенды есть. Ошибочно оставшийся процесс человек закроет кнопкой;
-ошибочно закрывшийся уносит с собой управление живыми стендами.
+**Незнание трактуется в пользу «остаться»**: поллера нет; он ещё не отдал первый снапшот;
+снапшот пришёл с `error` (отказ `_safe_build`); снапшот непробованный (`probed=False`);
+запись стенда не разобралась — во всех этих случаях считаем, что стенды есть. Ошибочно
+оставшийся процесс человек закроет кнопкой; ошибочно закрывшийся уносит с собой
+управление живыми стендами. (Полный перечень и его цена — «Уточнение 19.09.2026».)
 
 **`--desktop` — особый случай**: вкладки нет вовсе, окно и есть процесс, SSE-поток может
 пересоздаваться при перерисовке. Признак «никто не смотрит» там недостоверен, поэтому
@@ -135,6 +138,74 @@ elevated-перезапуск МЕНЯЕТ права процесса и пот
   «Основные», `0` выключает.
 - Деинсталляция после «Выхода» проверяется на VM (exe-поставка), а не на хосте издателя.
 
+
+## Уточнение 19.09.2026 (v0.12.2) — чего этому ADR не хватило в бою
+
+Живой инцидент владельца **18.09.2026 20:56**: диспетчер вышел по простою, три работающих
+стенда остались без управления, на экране была только ошибка связи. Решения этого ADR были
+верны; сломалось то, что ниже.
+
+### 1. Предикат простоя был тождественно ложным (GAP-383)
+
+`has_running_stands()` сравнивал `process.state` со строкой `"running"`, **которой в
+`ProbeState` нет вообще** (`ok`/`down`/`unknown`/`skipped`). На любом реальном снапшоте
+предикат отвечал «стендов нет», и конъюнкция из §2 вырождалась в одно слагаемое: таймер
+срабатывал ровно через 30 минут после закрытия вкладки, сколько бы стендов ни работало.
+
+Почему это пережило тесты: двойник снапшота в наборе сам подставлял то же выдуманное
+`"running"`. **Двойник, который беднее оригинала, проверяет не тот объект, что работает у
+пользователя** — теперь `_FakeSnapshot` повторяет поля настоящего `StatusSnapshot`
+(`probed`, `error`), а тест-сторож `test_probe_state_has_no_running_value` следит, чтобы
+значение `"running"` не «вернулось» в код вместе с чьей-нибудь правкой.
+
+### 2. Снапшот-отказ читался как пустота (GAP-383)
+
+`poller._safe_build` при любом сбое опроса честно возвращает `StatusSnapshot(stands=[],
+probed=False, error=...)`. Формально это «я не знаю», фактически — пустой список, который
+предикат принимал за «стендов нет». Декларация «незнание = остаёмся» в §2 существовала, но
+в коде покрывала только `poller is None` и `snapshot is None`.
+
+Теперь она покрывает весь перечень (см. таблицу выше). Цена ошибки несимметрична, и это
+единственный аргумент, который здесь имеет значение: лишний живой процесс закрывается
+кнопкой, лишнее завершение уносит управление стендами и объяснить себя не может.
+
+### 3. Автовыход не знал про подмену файлов под живым процессом (GAP-383)
+
+За два часа до инцидента владелец сделал `pip install standkit` поверх работающего
+диспетчера. Детект рассинхрона у хаба уже был (§4), но касался только страницы. Автовыход
+шёл прежним путём.
+
+**Решение: при рассинхроне версий (диск новее памяти) по простою НЕ выходить.** Плашка
+«перезапустите» и `POST /api/hub/restart` остаются действием ЧЕЛОВЕКА. Молчаливый
+самоперезапуск фонового процесса отвергнут: он относится к тому же классу действий,
+что и разбираемый инцидент — процесс без окна принимает за пользователя решение,
+последствия которого тот увидит как «всё пропало».
+
+### 4. Усыновлённые стенды не считались живыми (GAP-385)
+
+Условие простоя теперь — «нет НИ ОДНОГО стенда, живого **по факту пробы** (порт/pid)», а не
+«нет запущенных нами». Стенд с мёртвым родителем (`standkit.adopt`, бейдж
+`process.external`) — такой же повод остаться: он работает, и потерять управление им ничуть
+не лучше, чем своим. Это прямое следствие обещания §1 «детей не трогаем»: если выход
+штатно оставляет стенды сиротами, то сироты обязаны удерживать следующий выход.
+
+### 5. Причины завершения не доживали до разбора (GAP-384)
+
+Диспетчер живёт под `pythonw.exe`, у которого `sys.stderr` не подключён никуда (и бывает
+`None`), а все объяснения этого ADR писались через `print(..., file=sys.stderr)`. Самое
+громкое решение продукта — завершение процесса — было событием, о котором назавтра нельзя
+узнать ничего.
+
+Теперь есть `standkit_hub/hub_logging.py` (`%LOCALAPPDATA%\BPMkit\logs\hub.log`, ротация
+2 МБ × 5), и в него пишутся старт с версией, запрос штатного выхода, стоп-запрос, отказ
+фонового опроса с трейсбеком, необработанное исключение — и, главное, **факты, по которым
+принято решение об автовыходе** (`sse_client_count`, `has_running_stands`,
+`snapshot_probed`, `snapshot_error`), а не только сам факт выхода. Решение, записавшее свои
+основания, опровергается за минуту; решение, записавшее вывод, разбирается сутки.
+
+Настройка лога не имеет права уронить старт: любая беда — тихий отказ, логгер остаётся
+рабочим объектом.
+
 ## Отвергнутые варианты
 
 - **Иконка в трее с пунктом «Выход».** Отвергнута владельцем ранее и не пересматривалась:

{standkit-0.12.1 → standkit-0.12.2}/pyproject.toml

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

{standkit-0.12.1 → standkit-0.12.2}/standkit/__init__.py

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

{standkit-0.12.1 → standkit-0.12.2/standkit.egg-info}/PKG-INFO

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

{standkit-0.12.1 → standkit-0.12.2}/standkit.egg-info/SOURCES.txt

@@ -74,6 +74,7 @@ standkit_hub/config.py
 standkit_hub/consent_api.py
 standkit_hub/elevated_op.py
 standkit_hub/elevation.py
+standkit_hub/hub_logging.py
 standkit_hub/instance.py
 standkit_hub/license_api.py
 standkit_hub/logs_browser.py
@@ -123,6 +124,7 @@ tests/test_hub_exit_idle_restart.py
 tests/test_hub_fast_paint.py
 tests/test_hub_instance.py
 tests/test_hub_license_api.py
+tests/test_hub_logging.py
 tests/test_hub_logs_browser.py
 tests/test_hub_main_elevated.py
 tests/test_hub_mutex.py

{standkit-0.12.1 → standkit-0.12.2}/standkit_hub/__main__.py

@@ -35,15 +35,21 @@ import webbrowser
 from pathlib import Path
 from typing import Optional
 
+from standkit import __version__ as _standkit_version
 from standkit.platform import current_user_name, current_user_sid, is_elevated
 from standkit_hub import instance as _instance
 from standkit_hub.config import HubConfig
+from standkit_hub import hub_logging as _hub_logging
 from standkit_hub.mutex import acquire_hub_mutex
 from standkit_hub.elevation import ReparseGuardError, read_handoff, refusal_text, write_result_atomic
 from standkit_hub.security import InsecureBindError, generate_session_token
 from standkit_hub.server import DEFAULT_HUB_PORT, HubAlreadyRunning, bind_hub_server
 from standkit_hub.shortcut import install_desktop_shortcut, uninstall_desktop_shortcut
 
+# Лог диспетчера (GAP-384). Под pythonw.exe stderr не подключён никуда,
+# поэтому всё, что объясняет отказ или завершение, идёт в файл.
+_log = _hub_logging.logger()
+
 # Сколько в сумме ждать строгий bind перехваченного порта (GAP-311 В4/В6):
 # порт может освободиться не мгновенно даже после успешной остановки старого
 # процесса — повторяем bind, а не пытаемся один раз.
@@ -102,7 +108,7 @@ def _write_relaunch_result(result_file: str, *, status: str, message: str = "",
     try:
         write_result_atomic(Path(result_file), payload)
     except (OSError, ReparseGuardError) as exc:
-        print(f"[standkit-hub] не удалось записать результат перезапуска: {exc}", file=sys.stderr)
+        _log.warning(f"не удалось записать результат перезапуска: {exc}")
 
 
 def _describe_elevation(value) -> str:
@@ -144,22 +150,21 @@ def _takeover_running_instance(
         # напрямую; сейчас это просто впустую потраченное время пользователя.
         # Отказ немедленно, без ожидания.
         reason = "файл состояния работающего диспетчера не найден — закройте его вручную и запустите снова"
-        print(f"[standkit-hub] {reason}", file=sys.stderr)
+        _log.warning(f"{reason}")
         return False, reason
 
-    print(
-        f"[standkit-hub] перехватываю порт {exc.port} у работающего диспетчера "
+    _log.warning(f"перехватываю порт {exc.port} у работающего диспетчера "
         f"(pid {state.pid}, права администратора: {_describe_elevation(state.elevated)})"
     )
     ok, reason = _instance.stop_running_instance(state, run_dir=run_dir, requester_pid=os.getpid())
     if not ok:
         message = reason or f"не удалось остановить процесс {state.pid}"
-        print(f"[standkit-hub] {message} — перехват отменён", file=sys.stderr)
+        print(f"[standkit-hub] {message} — перехват отменён")
         return False, message
 
     if not _instance.wait_port_released(exc.host, exc.port):
         reason = f"порт {exc.port} так и не освободился — перехват отменён"
-        print(f"[standkit-hub] {reason}", file=sys.stderr)
+        _log.warning(f"{reason}")
         return False, reason
     return True, ""
 
@@ -190,12 +195,11 @@ def _warn_if_run_dir_outside_profile(run_dir: Path) -> None:
     try:
         resolved.relative_to(home)
     except ValueError:
-        print(
-            f"[standkit-hub] ВНИМАНИЕ: run_dir ({resolved}) находится вне домашнего "
+        _log.warning(
+            f"ВНИМАНИЕ: run_dir ({resolved}) находится вне домашнего "
             f"каталога пользователя ({home}) — файлы с правами 0o600 (handoff, состояние) "
             "на Windows не защищены ACL профиля; убедитесь, что каталог недоступен другим "
-            "локальным учётным записям",
-            file=sys.stderr,
+            "локальным учётным записям"
         )
 
 
@@ -297,13 +301,34 @@ def main(argv: list[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
 
+    # Лог поднимаем ПЕРВЫМ делом после разбора аргументов — до mutex/bind/
+    # state и до любой ветки, которая может завершиться отказом: инцидент
+    # 18.09.2026 показал, что дороже всего обходятся именно те сообщения,
+    # которые процесс успел бы написать ДО того, как что-то пошло не так.
+    # Неудача настройки лога старт НЕ прерывает (см. hub_logging.setup_logging).
+    _log_path = _hub_logging.setup_logging()
+    _log.info(
+        "старт standkit-hub: версия=%s python=%s pid=%s лог=%s",
+        _standkit_version, sys.version.split()[0], os.getpid(), _log_path or "(нет)",
+    )
+
+    # Необработанное исключение обязано остаться в логе, а не исчезнуть вместе
+    # с невидимым stderr: без этого «диспетчер просто пропал» — всё, что
+    # человек может сообщить о падении.
+    def _log_unhandled(exc_type, exc_value, exc_tb):
+        _log.critical("необработанное исключение — процесс завершается",
+                      exc_info=(exc_type, exc_value, exc_tb))
+        sys.__excepthook__(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _log_unhandled
+
     if args.elevated_op:
         # ДО любых bind/mutex/state/handoff: это одноразовый процесс "выполнить
         # и выйти", HTTP-сервер ему не нужен вовсе (см. standkit_hub.elevated_op).
         from standkit_hub import elevated_op as _elevated_op
 
         if not args.stand or not args.result_file:
-            print("[standkit-hub] --elevated-op требует --stand и --result-file", file=sys.stderr)
+            print("[standkit-hub] --elevated-op требует --stand и --result-file")
             return 1
         config_path = Path(args.config) if args.config else None
         return _elevated_op.run(
@@ -316,7 +341,7 @@ def main(argv: list[str] | None = None) -> int:
 
     if args.install_shortcut or args.uninstall_shortcut:
         result = install_desktop_shortcut() if args.install_shortcut else uninstall_desktop_shortcut()
-        print(f"[standkit-hub] {result.message}")
+        _log.warning(f"{result.message}")
         return 0 if result.ok else 1
 
     our_sid = current_user_sid()
@@ -333,7 +358,7 @@ def main(argv: list[str] | None = None) -> int:
     if args.initiator_sid:
         if our_sid and our_sid != args.initiator_sid:
             message = refusal_text(current_user_name())
-            print(f"[standkit-hub] {message}", file=sys.stderr)
+            print(f"[standkit-hub] {message}")
             if args.result_file:
                 _write_relaunch_result(
                     args.result_file, status="refused", message=message, user=current_user_name()
@@ -356,7 +381,7 @@ def main(argv: list[str] | None = None) -> int:
     try:
         config.ensure_registry_dir()
     except OSError as exc:
-        print(f"[standkit-hub] не удалось подготовить папку реестра: {exc}", file=sys.stderr)
+        _log.warning(f"не удалось подготовить папку реестра: {exc}")
 
     run_dir = config.resolve_run_dir()
     _warn_if_run_dir_outside_profile(run_dir)
@@ -369,10 +394,9 @@ def main(argv: list[str] | None = None) -> int:
     if args.session_token_file:
         session_token = read_handoff(Path(args.session_token_file)) or ""
         if not session_token:
-            print(
-                "[standkit-hub] сессию предыдущего экземпляра перенести не удалось "
-                "(файл передачи отсутствует или протух) — открывайте дашборд заново по ярлыку",
-                file=sys.stderr,
+            _log.warning(
+                "сессию предыдущего экземпляра перенести не удалось "
+                "(файл передачи отсутствует или протух) — открывайте дашборд заново по ярлыку"
             )
     if not session_token:
         session_token = generate_session_token()
@@ -389,7 +413,7 @@ def main(argv: list[str] | None = None) -> int:
     def _report_port_busy(requested: int, exc: OSError) -> None:
         # Печатаем ДО повторного bind'а: пользователь должен понимать, почему
         # адрес в консоли/закладке вдруг отличается от привычного.
-        print(f"[standkit-hub] порт {requested} занят ({exc.strerror or exc}) — беру свободный", file=sys.stderr)
+        _log.warning(f"порт {requested} занят ({exc.strerror or exc}) — беру свободный")
 
     def _bind():
         return bind_hub_server(
@@ -439,7 +463,7 @@ def main(argv: list[str] | None = None) -> int:
                 httpd = _bind_with_retries(_bind_strict)
             except (HubAlreadyRunning, InsecureBindError, OSError) as exc2:
                 message = f"перехват не удался: {exc2}"
-                print(f"[standkit-hub] {message}", file=sys.stderr)
+                _log.warning(f"{message}")
                 if args.result_file:
                     _write_relaunch_result(args.result_file, status="failed", message=message)
                 return 1
@@ -453,13 +477,13 @@ def main(argv: list[str] | None = None) -> int:
             # не удалось остановить и т.п.), если она есть, — а не
             # обобщённый текст.
             message = takeover_reason or "перехват порта не выполнен: работающий экземпляр перехвату не подлежит"
-            print(f"[standkit-hub] {message}", file=sys.stderr)
+            _log.warning(f"{message}")
             _write_relaunch_result(args.result_file, status="failed", message=message)
             return 1
         else:
             return _open_running_instance(exc, no_browser=args.no_browser)
     except InsecureBindError as exc:
-        print(f"[standkit-hub] {exc}", file=sys.stderr)
+        _log.warning(f"{exc}")
         if args.result_file:
             _write_relaunch_result(args.result_file, status="failed", message=str(exc))
         return 1
@@ -485,7 +509,7 @@ def main(argv: list[str] | None = None) -> int:
                 message = f"порт {args.port} занят другим приложением"
         else:
             message = f"не удалось занять {args.host}:{args.port} — {exc}"
-        print(f"[standkit-hub] {message}", file=sys.stderr)
+        _log.warning(f"{message}")
         if args.result_file:
             _write_relaunch_result(args.result_file, status="failed", message=message)
         return 1
@@ -499,7 +523,7 @@ def main(argv: list[str] | None = None) -> int:
 
     actual_port = httpd.server_address[1]
     if args.port and actual_port != args.port:
-        print(f"[standkit-hub] порт {args.port} занят, слушаю {actual_port}")
+        _log.warning(f"порт {args.port} занят, слушаю {actual_port}")
     # Файл состояния — чтобы СЛЕДУЮЩИЙ запуск знал, кого он видит на порту
     # (в т.ч. с правами администратора тот процесс или нет).
     elevated = is_elevated()
@@ -509,7 +533,7 @@ def main(argv: list[str] | None = None) -> int:
             _instance.current_state(args.host, actual_port, elevated=elevated, user_sid=our_sid),
         )
     except (OSError, ReparseGuardError) as exc:
-        print(f"[standkit-hub] не удалось записать файл состояния: {exc}", file=sys.stderr)
+        print(f"[standkit-hub] не удалось записать файл состояния: {exc}")
 
     # Д-3: штатный выход (кнопка «Выход» и автовыход по простою) обязан убрать
     # файл состояния ДО завершения процесса — иначе следующий запуск увидит
@@ -605,9 +629,8 @@ def _serve_inner(httpd, *, args, url: str) -> int:
         try:
             import webview  # type: ignore
         except ImportError:
-            print(
-                "[standkit-hub] pywebview не установлен (pip install standkit[desktop]) — открываю в системном браузере",
-                file=sys.stderr,
+            _log.warning(
+                "pywebview не установлен (pip install standkit[desktop]) — открываю в системном браузере"
             )
             if not args.no_browser:
                 webbrowser.open(url)

{standkit-0.12.1 → standkit-0.12.2}/standkit_hub/config.py

@@ -266,11 +266,16 @@ class HubConfig:
     log_dir: str = ""
     refresh_interval_sec: int = _DEFAULT_REFRESH_INTERVAL_SEC
     # Автовыход по простою (Д-3/GAP-276), МИНУТЫ; 0 — выключено. Простой =
-    # «нет ни одного открытого SSE-клиента И ни одного running-стенда»: первое
+    # «нет ни одного открытого SSE-клиента И ни одного ЖИВОГО стенда»: первое
     # означает «дашборд никто не смотрит», второе — «диспетчер сейчас ничем не
     # управляет». Оба условия обязательны вместе: закрытая вкладка при живых
     # стендах — норма (стенды поднимали через диспетчер и ждут), а открытая
     # вкладка без стендов — человек смотрит на пустой список, но смотрит.
+    #
+    # ЖИВОЙ — по факту пробы (``ProbeState.OK``: порт/pid), включая стенды,
+    # поднятые мимо диспетчера и усыновлённые (GAP-385). Любое незнание
+    # (отказ опроса, непробованный слепок) трактуется как «стенды есть»
+    # (GAP-383, ADR-0007): цена лишнего завершения несимметрично выше.
     idle_shutdown_min: int = _DEFAULT_IDLE_SHUTDOWN_MIN
     # light | dark | auto (см. normalize_theme). Подставляется сервером прямо
     # в атрибут data-theme отдаваемого index.html — тема применяется ДО

standkit-0.12.2/standkit_hub/hub_logging.py

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+"""
+Лог диспетчера в ФАЙЛ (GAP-384) — STDLIB-ONLY, как и весь standkit_hub.
+
+ЗАЧЕМ ЭТОТ МОДУЛЬ ВООБЩЕ ПОЯВИЛСЯ. Инцидент 18.09.2026 20:56: диспетчер вышел
+сам (автовыход по простою при живых стендах, GAP-383), три стенда осиротели,
+владелец увидел на экране только ошибку связи. Разбирать было нечего.
+
+Причина слепоты структурная, а не случайная: ярлык запускает диспетчер через
+``pythonw.exe`` — процесс БЕЗ консоли, у которого ``sys.stderr`` не подключён
+никуда (а на Windows он может быть и ``None``). Все объяснения диспетчера о
+том, почему он завершается — «простой N минут», «получен стоп-запрос»,
+«перехват порта» — были написаны через ``print(..., file=sys.stderr)``, то
+есть существовали ровно на время своего вывода и никуда не попадали.
+
+Отсюда правило, которое этот модуль обслуживает: **всё, что объясняет
+завершение процесса или необработанный отказ, пишется сюда, а не в stderr.**
+Лог — единственный свидетель для процесса, у которого нет ни окна, ни консоли,
+ни того, кто смотрел бы на них в 20:56.
+
+Ротация обязательна и не обсуждается: забытый диспетчер живёт неделями, и
+неограниченный файл однажды становится второй аварией поверх первой.
+
+Настройка логирования НЕ ИМЕЕТ ПРАВА уронить старт. Диспетчер без лога хуже
+диспетчера с логом, но несравнимо лучше не запустившегося: любая беда при
+создании каталога/файла — тихий отказ с ``None``, логгер при этом остаётся
+рабочим объектом, и все вызовы выше по коду продолжают быть безопасными.
+"""
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Имя логгера — общее для всего диспетчера: и сервер, и поллер, и __main__
+# пишут в один файл, потому что разбирают их вместе («что было в 20:56»), а не
+# по отдельности.
+LOGGER_NAME = "standkit_hub"
+
+LOG_FILE_NAME = "hub.log"
+
+# 2 МБ × 5 — заведомо больше любого разумного разбора и заведомо меньше
+# «файл съел диск у человека, который про диспетчер забыл».
+MAX_BYTES = 2 * 1024 * 1024
+BACKUP_COUNT = 5
+
+_LOG_FORMAT = "%(asctime)s %(levelname)-7s [%(name)s] %(message)s"
+
+
+def logger() -> logging.Logger:
+    """Логгер диспетчера. Всегда возвращает рабочий объект — см. докстринг модуля."""
+    return logging.getLogger(LOGGER_NAME)
+
+
+def resolve_log_dir(explicit: "Optional[Path | str]" = None) -> Path:
+    """
+    Каталог лога. Явный аргумент > ``%LOCALAPPDATA%`` > платформенный дефолт.
+
+    Дефолт ОБЯЗАН быть при любом состоянии окружения: «не смогли определить
+    каталог» здесь означает «следующий инцидент снова разбирать нечем».
+    Поэтому последний фолбэк — домашний каталог, который есть всегда.
+    """
+    if explicit:
+        return Path(explicit).expanduser()
+
+    local_appdata = os.environ.get("LOCALAPPDATA")
+    if local_appdata:
+        return Path(local_appdata) / "BPMkit" / "logs"
+
+    if sys.platform == "win32":
+        # Windows без LOCALAPPDATA — экзотика (служба, урезанный профиль), но
+        # молчать в ней нельзя ровно так же, как и в обычном сеансе.
+        return Path.home() / "AppData" / "Local" / "BPMkit" / "logs"
+
+    # POSIX: тот же смысл, что у %LOCALAPPDATA% — состояние приложения.
+    state_home = os.environ.get("XDG_STATE_HOME")
+    if state_home:
+        return Path(state_home) / "BPMkit" / "logs"
+    return Path.home() / ".local" / "state" / "BPMkit" / "logs"
+
+
+def resolve_log_path(explicit_dir: "Optional[Path | str]" = None) -> Path:
+    """Полный путь файла лога (``<каталог>/hub.log``)."""
+    return resolve_log_dir(explicit_dir) / LOG_FILE_NAME
+
+
+def setup_logging(*, log_dir: "Optional[Path | str]" = None,
+                  level: int = logging.INFO,
+                  force: bool = False) -> Optional[Path]:
+    """
+    Подключает ротируемый файловый обработчик. Возвращает путь лога или
+    ``None``, если настроить не удалось (старт при этом НЕ прерывается).
+
+    ``force`` — пересобрать обработчики (нужен тестам и повторному запуску в
+    одном процессе). Без него повторный вызов идемпотентен: второй файловый
+    обработчик означал бы дублирование каждой строки.
+    """
+    log = logger()
+    if force:
+        reset_logging()
+    elif any(isinstance(h, logging.handlers.RotatingFileHandler) for h in log.handlers):
+        return getattr(log, "_standkit_log_path", None)
+
+    log.setLevel(level)
+    # Диспетчер — не библиотека: свои записи он не отдаёт наверх, где их
+    # подхватил бы чей-нибудь basicConfig и снова увёл в мёртвый stderr.
+    log.propagate = False
+
+    path = resolve_log_path(log_dir)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handler = logging.handlers.RotatingFileHandler(
+            path, maxBytes=MAX_BYTES, backupCount=BACKUP_COUNT, encoding="utf-8")
+    except OSError:
+        # Каталог занят файлом, нет прав, диск полон — молча остаёмся без
+        # файла. Ронять из-за лога процесс, ради живучести которого лог и
+        # заводился, было бы прямым противоречием.
+        return None
+
+    handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+    log.addHandler(handler)
+
+    # Консоль — ТОЛЬКО если она есть (обычный python.exe при отладке). Под
+    # pythonw.exe ``sys.stderr`` бывает ``None``, и StreamHandler(None) сам
+    # стал бы источником отказов в каждой записи.
+    if sys.stderr is not None:
+        stream = logging.StreamHandler(sys.stderr)
+        stream.setFormatter(logging.Formatter(_LOG_FORMAT))
+        log.addHandler(stream)
+
+    setattr(log, "_standkit_log_path", path)
+    return path
+
+
+def current_log_path() -> Optional[Path]:
+    """Путь активного лога или ``None`` — то, что показывает ``self_check``."""
+    return getattr(logger(), "_standkit_log_path", None)
+
+
+def reset_logging() -> None:
+    """Снимает обработчики (тесты; повторная настройка в одном процессе)."""
+    log = logger()
+    for handler in list(log.handlers):
+        log.removeHandler(handler)
+        try:
+            handler.close()
+        except Exception:  # noqa: BLE001 - уборка не имеет права падать
+            pass
+    if hasattr(log, "_standkit_log_path"):
+        delattr(log, "_standkit_log_path")