standkit 0.10.0__tar.gz → 0.12.2__tar.gz

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

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

{standkit-0.10.0 → standkit-0.12.2}/docs/BACKLOG.md

@@ -73,8 +73,9 @@ Redis теперь объясняются словами (`details['http_reason'
 | Ярлык на рабочем столе для **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`) |
+| Остановка хаба, когда дашборд никто не смотрит (idle-shutdown) | **реализовано** (0.12.0, ADR-0007) — `HubConfig.idle_shutdown_min`, 30 мин по умолчанию, `0` выключает. Простой = нет открытых SSE-клиентов И нет `running`-стендов (оба условия обязательны вместе); в `--desktop` — только по стендам. Таймер сбрасывается активностью, настройка перечитывается без перезапуска | `standkit_hub/server.py::_IdleShutdownWatcher`, `standkit_hub/config.py::idle_shutdown_min` |
+| Остановка хаба из интерфейса (кнопка «Завершить работу диспетчера») | **реализовано** (0.12.0, ADR-0007) — кнопка «Выход» в шапке и в «Настройки → О программе», `POST /api/hub/shutdown`. Освобождает мьютекс установщика сразу, чистит файл состояния, потомков (запущенные стенды, локальный агент) НЕ трогает | `standkit_hub/server.py::HubHTTPServer.request_self_shutdown`, `web/app.js::exitHubFlow` |
+| Перезапуск хаба из интерфейса без повышения прав | **реализовано** (0.12.0, ADR-0007, GAP-276) — `POST /api/hub/restart`, переиспользует машинерию elevated-перезапуска, но порождает процесс обычным `spawn_hidden` без UAC. Кнопки — в плашке рассинхрона версий и в «О программе» | `standkit_hub/server.py::_api_hub_restart`, `web/app.js::restartHubFlow` |
 
 ## Секреты
 

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

@@ -5,6 +5,269 @@
 
 ## [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
+
+### Добавлено
+
+- **Кукбук пользователя как отдельный артефакт канала (GAP-361).** Модуль
+  `standkit_companion/cookbook.py`: документ приезжает по каналу издателя
+  пассажиром на `sync_patterns`/`check_update`, ложится в
+  `%APPDATA%\BPMkit\docs\cookbook.html` атомарной заменой после проверки
+  подписи и сверки версии из `/meta`. Слот `staged` релизного канала и
+  инварианты GAP-212/279 не затронуты: у кукбука свой узкий поток.
+  Отказ попутчика не роняет несущую операцию; 404 канала — штатный пропуск
+  тика (`skipped`), пока издатель не выложил документ.
+
+### Примечание к версии
+
+- Выпуск PATCH поверх 0.12.0: содержимое 0.12.0 (PR #55, GAP-361) на PyPI
+  **не публиковалось** — токена не было, а установщик BPMkit 1.1.75 собран с
+  указателем `d79f3cc` (без кукбук-канала). Отдельный номер 0.12.1 нужен,
+  чтобы опубликованный пакет и собранные установщики нельзя было спутать по
+  одному и тому же номеру.
+
+## [0.12.0] — 2026-09-17
+
+### Добавлено
+
+- **Кнопка «Выход» в диспетчере (Д-3).** Диспетчер живёт под `pythonw.exe` без
+  окна: закрытая вкладка НЕ завершает процесс, и он до перезагрузки держит порт
+  8770 и именованный мьютекс, из-за которого установщик BPMkit отказывается
+  работать («диспетчер запущен»). Теперь выход есть в шапке (иконка) и в
+  «Настройки → О программе», с подтверждением, которое прямо снимает главный
+  страх: «Запущенные стенды продолжат работать — выход останавливает только сам
+  диспетчер». Трея по-прежнему нет. Новый маршрут `POST /api/hub/shutdown`
+  (токен записи + локальный Origin): освобождает мьютекс СРАЗУ (ради него выход
+  чаще всего и нажимают), чистит файл состояния экземпляра, завершает сервер тем
+  же путём, что перехват порта, и НЕ трогает потомков — запущенные стенды и
+  локальный агент переживают выход.
+- **Автовыход по простою** — `HubConfig.idle_shutdown_min`, по умолчанию 30
+  минут, `0` выключает. Условие простоя — конъюнкция: нет ни одного открытого
+  SSE-клиента (дашборд закрыт) И нет ни одного `running`-стенда (диспетчер ничем
+  не управляет). Оба слагаемых обязательны вместе: закрытая вкладка при живых
+  стендах — штатная работа, а открытая вкладка без стендов означает, что человек
+  смотрит на экран. Незнание (поллер ещё не отдал первый снапшот) трактуется в
+  пользу «остаться». В режиме `--desktop` признак «никто не смотрит»
+  недостоверен, поэтому условие сводится только к стендам. Настройка
+  перечитывается перед каждой проверкой — правка в форме применяется без
+  перезапуска. Поле — в «Настройки → Основные».
+- **`POST /api/hub/restart` — перезапуск БЕЗ повышения прав (GAP-276 п.3).** Та
+  же машинерия, что у `restart-elevated` (`--takeover`, файл передачи сессии,
+  `result_file`, ожидание возврата вкладкой), но новый процесс порождается
+  обычным `spawn_hidden`, а не `ShellExecuteW(runas)` — окна UAC нет и права
+  остаются теми же. Чинит рассинхрон «код старый, статика новая» после
+  `pip install` поверх работающего хаба. Кнопки — в плашке рассинхрона и в
+  «О программе».
+- **Детект рассинхрона версий страницы и сервера (GAP-276 п.2).** Статика
+  читается с диска на каждый запрос, код сервера живёт в памяти процесса:
+  обновление пакета под работающим хабом даёт новую страницу на старом сервере.
+  Сервер подставляет в `<meta name="standkit-build">` версию, прочитанную из
+  файла пакета НА ДИСКЕ (`on_disk_standkit_version`, а не `standkit.__version__`
+  из памяти — именно в этом расхождении и состоит гэп), страница сверяет её с
+  `/api/version` и при расхождении показывает плашку «Диспетчер обновлён до X,
+  сервер работает на Y — перезапустить» с кнопкой.
+
+### Исправлено
+
+- **Неизвестный маршрут `/api/*` отвечает человеческим текстом, а не сырым
+  `not found` (GAP-276 п.4).** Живой случай 11.09.2026: раздел «Лицензия» новой
+  страницы позвал маршрут, которого у старого сервера ещё не было, и
+  пользователь увидел `not found` как «лицензия не найдена» — сообщение,
+  уводящее в прямо противоположную от причины сторону. Теперь: «Сервер
+  диспетчера не поддерживает эту функцию — возможно, он устарел. Перезапустите
+  диспетчер и повторите», а если страница прислала свою версию сборки
+  (`X-Standkit-Build`) и она новее — обе версии называются прямо.
+- **Тесты через `node` больше не падают на русской Windows.** `subprocess.run`
+  с `text=True` без явной кодировки декодировал UTF-8-вывод node локалью
+  процесса (cp1251), и все проверки русских сообщений падали на мусоре вместо
+  текста. Пять тестов `*_via_node` в `test_hub_elevation_ui.py` и
+  `test_hub_consent_api.py`.
+- **`test_find_cli_returns_none_when_nothing_found` больше не зависит от того,
+  где запущен.** `extra_roots` не изолировал обход вверх от пакета: при
+  editable-установке прямо из dev-репозитория издателя четвёртый уровень вверх —
+  корень `bpmsoft-mcp` с настоящим `BPMkit/server/main.py`, и тест падал не
+  из-за кода.
+
+## [0.11.5] — 2026-09-16
+
+### Добавлено
+
+- **Раздел «Данные и телеметрия» в настройках диспетчера (GAP-332).** Показывает и меняет
+  четыре согласия MCP BPMkit (обезличенная телеметрия использования, приложение журнала к
+  обращениям, отправка кандидатов-паттернов, отправка кандидатов) — тем же приёмом, каким
+  сделана лицензия: диспетчер только читает и передаёт CLI (`setup consent-info --json` /
+  `setup consent-set`), своей логики согласий у него нет. Каждый переключатель — со
+  справкой-«?», что именно уходит; строка состояния «последняя отправка / накоплено /
+  приёмник / установка», отметка о принятии соглашения, кнопка «Показать, что уйдёт» с
+  предпросмотром текста CLI. Раздел виден всегда, включая свободную редакцию и отсутствие
+  CLI рядом — тогда вместо переключателей честная подсказка с причиной и путём в
+  «Настройки → Основные».
+- `GET /api/consent` и `POST /api/consent` — новые маршруты хаба
+  (`standkit_hub/consent_api.py`), тот же контур авторизации и CSRF-защиты, что у
+  `/api/license`.
+
+## [0.11.4] — 2026-09-16
+
+### Исправлено
+
+- **После перезапуска с правами окно ожидания закрывается само.** Если новый процесс
+  диспетчера занимал порт быстрее интервала опроса, вкладка не видела обрыва связи и
+  ждала его до таймаута: оверлей висел, щит оставался красным, хотя диспетчер уже работал
+  с правами. Теперь ответ `elevated: true` (или исчезнувшее состояние ожидания) от того же
+  адреса считается новым процессом — страница перезагружается.
+
+## [0.11.3] — 2026-09-16
+
+### Изменено
+
+- **Справка у полей «Настройки → Основные».** Длинные серые пояснения под полями заменены
+  маленькой иконкой «?» рядом с подписью: при наведении или фокусе — для чего поле и
+  пример значения (реестр стендов, CLI BPMkit, каталог pid-файлов, каталог логов, интервал
+  опроса). Пустые каталоги pid-файлов и логов показывают фактический каталог по умолчанию
+  вместо «не задано».
+
+## [0.11.2] — 2026-09-16
+
+### Изменено
+
+- **Щит-статус прав администратора (GAP-311, решение владельца 16.09.2026,
+  пересматривает решение 15.09.2026).** На Windows значок в шапке виден теперь
+  ВСЕГДА, а не только когда прав не хватает — только иконка, без подписи:
+  зелёный (галочка) — права есть, клик открывает «О программе» и ничего не
+  перезапускает; красный (восклицательный знак) — прав нет, клик запускает
+  перезапуск с правами через UAC, как раньше; серый — определить права не
+  удалось. Кнопка — обычный квадрат 34×34, без своей рамки/фона-пилюли.
+
+### Добавлено
+
+- **Поле «CLI BPMkit» в «Настройки → Основные»** (рядом с «Реестр стендов») —
+  раньше жило только в «Настройки → Обновления», а тот раздел скрыт целиком в
+  свободной редакции, хотя сам CLI (проверка лицензии, версия MCP) нужен
+  независимо от неё. Под полем — строка «Сейчас используется: …» / «Сейчас:
+  CLI не найден». Сохранение настроек сбрасывает кэш сводки лицензии И кэш
+  лицензионного контекста канала обновлений, чтобы статус и версия MCP
+  обновились немедленно, а не по истечении их TTL.
+- **`GET /api/license`: поля `cli` и `cli_source`.** `cli` — итоговая команда
+  резолва CLI строкой (`subprocess.list2cmdline`) или `null`; `cli_source` —
+  `"settings"`/`"env"`/`"auto"`/`null`. Вычисляются резолвом, без лишнего
+  запуска CLI.
+
+### Исправлено
+
+- **Версия MCP в UI — только фактическая.** Плейсхолдер «как в поставке»
+  убран: показывается версия из `GET /api/license` (`mcp_version`, отдаёт CLI
+  `setup license-info --json`) либо, если её нет, `current_version` канала
+  обновлений; если версия неизвестна вовсе — честно «неизвестна» (с уточнением
+  «не найден CLI BPMkit», если резолв не нашёл CLI). Строка состояния внизу
+  (`#sl-mcp`) больше не прячет сегмент «MCP» при неизвестной версии — она
+  видна с подсказкой, что поправить в «Настройки → Основные».
+
+## [0.11.1] — 2026-09-16
+
+### Исправлено
+
+- **Остановленная служба W3SVC больше не выдаётся за «обрыв канала управления IIS».**
+  Живьём на iis19: `appcmd start site` при остановленной «Службе веб-публикаций»
+  отвечает `0x80010006` — тем же текстом, что транзиентный сбой RPC, и диспетчер
+  советовал просто повторить. Теперь при таком ответе сверяется состояние служб WAS/W3SVC,
+  и ошибка называет остановленную службу и команду запуска. Проверка прав администратора
+  идёт раньше классификации RPC: без прав appcmd отказывает под любым текстом.
+- **Щит «без прав администратора» не ломает шапку**: подпись переносилась в две строки
+  внутри квадратной кнопки 34×34.
+
+## [0.11.0] — 2026-09-15
+
+### Добавлено
+
+- **Права администратора для IIS прямо из диспетчера (GAP-311).** Разбор —
+  [ADR-0006](adr/0006-hub-elevated-restart.md).
+  - **Щит «без прав администратора» в шапке** — виден только когда диспетчер работает
+    без прав (`GET /api/hub/elevation`). По клику, после подтверждения, диспетчер
+    перезапускается через окно Windows (UAC) на том же адресе, открытая вкладка
+    переподключается сама: сессия переезжает одноразовым файлом, не аргументом
+    командной строки.
+  - **Кнопки в ошибке IIS.** Ответ действия со стендом при нехватке прав теперь несёт
+    `elevation_required: true`, и в сообщении есть «Перезапустить с правами
+    администратора» и «Только эту операцию».
+  - **Однократная операция с правами** (`POST /api/hub/elevated-op`, режим
+    `--elevated-op start|stop|restart --stand`) — одна операция над IIS-стендом через
+    окно Windows, сам диспетчер остаётся без прав. Также доступна в «Настройки → О
+    программе», где видно и текущее состояние прав.
+  - **Отказ при подтверждении под другой учётной записью** — новый процесс сверяет SID
+    и ничего не делает, старый диспетчер показывает пояснение и продолжает работать.
+
+### Исправлено
+
+- **Запуск ярлыка «от имени администратора» больше не выглядит как «ничего не
+  произошло».** Раньше новый процесс видел работающий диспетчер на порту 8770, открывал
+  браузер на СТАРОМ, без прав, и выходил. Теперь он перехватывает порт у неэлевированного
+  экземпляра (файл состояния `standkit_hub/instance.py`).
+- **Перехват порта не убивает запущенные стенды.** Старый диспетчер останавливается по
+  запросу (файл stop-request в `run_dir`) и сам закрывает сокет; эскалация, если он
+  завис, завершает только его pid (`taskkill` без `/T`) и только после подтверждения у
+  ОС, что это действительно диспетчер. Новый процесс занимает строго тот же порт.
+- **`appcmd.exe` у 32-битного Python** резолвится через `Sysnative` (раньше
+  WOW64-редирект давал «файл не найден», похожий на отказ по правам).
+- **Мьютекс диспетчера, созданный с правами администратора, виден установщику BPMkit**
+  без прав — явный security descriptor.
+- Проверка «процесс с правами администратора» переехала в
+  `standkit.platform.is_elevated()`; добавлены `current_user_sid()`,
+  `current_user_name()`, `process_create_time()`.
+
 ## [0.10.0] — 2026-09-08
 
 ### Добавлено
@@ -792,6 +1055,12 @@
 - Первый публичный релиз ядра `standkit` + агента `standkit_agent` + веб-дашборда
   `standkit_hub` на PyPI; фронт-README, `docs/REMOTE_STANDS.md`, скриншоты.
 
+[0.11.5]: https://pypi.org/project/standkit/0.11.5/
+[0.11.4]: https://pypi.org/project/standkit/0.11.4/
+[0.11.3]: https://pypi.org/project/standkit/0.11.3/
+[0.11.2]: https://pypi.org/project/standkit/0.11.2/
+[0.11.1]: https://pypi.org/project/standkit/0.11.1/
+[0.11.0]: https://pypi.org/project/standkit/0.11.0/
 [0.10.0]: https://pypi.org/project/standkit/0.10.0/
 [0.9.0]: https://pypi.org/project/standkit/0.9.0/
 [0.8.0]: https://pypi.org/project/standkit/0.8.0/

{standkit-0.10.0 → standkit-0.12.2}/docs/HOSTING.md

@@ -162,11 +162,27 @@ Health-проба «процесс» (`standkit.health.check_stand`) для `iis
   что требует прав администратора; без elevation любая IIS-операция падает с
   ошибкой прав (например, `код 1168` / «не удалось открыть файл конфигурации
   из-за отсутствия необходимых разрешений»). Членства в группе `IIS_IUSRS`
-  **недостаточно**. Как запускать elevated: ярлык/консоль → правый клик →
-  «Запуск от имени администратора», либо из уже поднятой административной
-  консоли `standkit-hub`. Диспетчер в такой ситуации отдаёт понятную подсказку
-  «запустите от имени администратора» в тексте ошибки. Живая приёмка — на
-  стенде с реальным IIS.
+  **недостаточно**. Как запускать elevated:
+
+  - **из самого дашборда** — щит «без прав администратора» в шапке (виден, только
+    когда прав действительно нет) или кнопка «Перезапустить с правами администратора»
+    в сообщении об ошибке: подтвердите окно Windows, и диспетчер поднимется заново на
+    том же адресе, вкладка переподключится сама. Запущенные стенды перезапуск не
+    трогает. Если окно подтвердили под другой учётной записью — диспетчер откажет с
+    пояснением и продолжит работать без прав;
+  - **только одну операцию** — «Только эту операцию» в сообщении об ошибке или блок
+    «Однократная операция с правами администратора» в «Настройки → О программе»:
+    старт/стоп/перезапуск IIS-стенда с запросом прав, сам диспетчер остаётся без них.
+    Разбор обоих путей — [ADR-0006](adr/0006-hub-elevated-restart.md);
+  - ярлык/консоль → правый клик → «Запуск от имени администратора» (elevated
+    экземпляр заменит собой уже работающий обычный; до 0.11.0 он молча открывал
+    браузер на старом, и казалось, что запуск не сработал);
+  - раз и навсегда — свойства ярлыка → «Дополнительно» → галка «Запуск от
+    имени администратора»; либо `standkit-hub` из уже поднятой
+    административной консоли.
+
+  Диспетчер в такой ситуации отдаёт понятную подсказку «запустите от имени
+  администратора» в тексте ошибки. Живая приёмка — на стенде с реальным IIS.
 - **Docker**: установленный Docker Engine (`docker` в PATH процесса
   standkit); для compose-режима — плагин `docker compose` (Compose V2).
 - **Kubernetes**: установленный `kubectl` в PATH процесса standkit и

{standkit-0.10.0 → standkit-0.12.2}/docs/README.md

@@ -38,7 +38,7 @@
 | Документ | О чём |
 |---|---|
 | [ARCHITECTURE.md](ARCHITECTURE.md) | Краткое зеркало архитектуры: что за что отвечает, границы модулей |
-| [adr/](adr/) | Архитектурные решения с разбором альтернатив — [0001 хостинг-бэкенды](adr/0001-hosting-backends.md) · [0002 k8s](adr/0002-k8s-backend.md) · [0003 логи удалённых стендов](adr/0003-remote-log-browsing.md) · [0004 IIS по Site](adr/0004-iis-site-scoped-lifecycle.md) · [0005 транспорт канала обновлений в MIT-ядре](adr/0005-companion-transport-in-mit-core.md) |
+| [adr/](adr/) | Архитектурные решения с разбором альтернатив — [0001 хостинг-бэкенды](adr/0001-hosting-backends.md) · [0002 k8s](adr/0002-k8s-backend.md) · [0003 логи удалённых стендов](adr/0003-remote-log-browsing.md) · [0004 IIS по Site](adr/0004-iis-site-scoped-lifecycle.md) · [0005 транспорт канала обновлений в MIT-ядре](adr/0005-companion-transport-in-mit-core.md) · [0006 права администратора для IIS](adr/0006-hub-elevated-restart.md) |
 | [CHANGELOG.md](CHANGELOG.md) | История изменений по версиям (Keep a Changelog + SemVer) |
 | [research/](research/) | Проработки без принятых решений — [companion v2: CI/CD через тонкого агента](research/companion-v2-cicd-thin-agent.md) |
 

standkit-0.12.2/docs/adr/0006-hub-elevated-restart.md

@@ -0,0 +1,130 @@
+# ADR-0006 — Права администратора для IIS: перезапуск диспетчера через UAC и однократная операция
+
+- Статус: **Принято / реализовано** (v0.11.0, GAP-311, 15.09.2026). Первая версия
+  перезапуска написана 19.08.2026 в ветке `feat/hub-elevated-restart` (тогда под номером
+  ADR-0005, который к мержу оказался занят ADR о канале обновлений), перенесена в
+  `main` с доработками по двум раундам ревью.
+- Контекст-владелец: Владимир Терновский
+- Связано: [ADR-0004](0004-iis-site-scoped-lifecycle.md) (диагноз «нехватка прав» у `appcmd`),
+  [HOSTING.md](../HOSTING.md); в dev-репо BPMkit — GAP-282 (путь без прав: перезапуск
+  приложения сменой `LastWriteTime` у `web.config`) и GAP-311.
+
+## Контекст и проблема
+
+Управление стендами IIS идёт через `appcmd.exe`, а он без прав администратора не работает
+в принципе: не читает даже `…\inetsrv\config\redirection.config`. Диспетчер честно называл
+причину и советовал «запустите standkit-hub с правами администратора», но выполнить совет
+было нельзя:
+
+1. Ошибка остановки IIS-стенда с подсказкой про права.
+2. Пользователь запускает ярлык «от имени администратора».
+3. Ничего не меняется: новый процесс видит на порту 8770 работающий диспетчер
+   (single-instance, `HubAlreadyRunning`), открывает браузер на СТАРОМ — без прав — и выходит.
+
+Живьём воспроизведено дважды: 19.08.2026 и 15.09.2026 (`TokenIsElevated=0` у работающего
+`pythonw -m standkit_hub`, хотя пользователь уверен, что запускал от администратора).
+
+## Решение
+
+### 1. Видно, что прав нет
+
+`GET /api/hub/elevation` → `{supported, elevated, can_restart, reason, user, restart}`.
+Щит «без прав администратора» в шапке показывается **только когда прав нет** (решение
+владельца). С правами и на не-Windows щита нет; состояние прав всегда видно в
+«Настройки → О программе». Ошибка действия со стендом при нехватке прав приходит с
+признаком `elevation_required: true`, и в сообщении две кнопки — «Перезапустить с правами
+администратора» и «Только эту операцию».
+
+### 2. Перезапуск диспетчера с правами (П1)
+
+`POST /api/hub/restart-elevated`:
+
+```
+старый хаб                                   новый хаб (runas, --takeover)
+──────────                                   ─────────────────────────────
+restart=requesting (под lock)
+handoff-файл с токеном сессии
+ShellExecuteW runas ──UAC «Нет»──> 409 cancelled, restart=null, handoff удалён
+         │ «Да»
+202, restart=pending,                        1. SID != --initiator-sid → result: refused, выход
+наблюдатель result-файла                     2. читает handoff (одноразово)
+         │                                   3. пишет stop-request (pid старого)
+stop-request для моего pid ───────────────── 4. ждёт освобождения порта
+штатный shutdown, выход                      5. bind СТРОГО на тот же порт (повторы)
+(дочерние стенды и агент живут)              6. result: serving | failed (+причина)
+```
+
+- Старый процесс завершается **только** по stop-request — не «через секунду после 202».
+  Отказ под другой учётной записью, сбой перехвата или таймаут оставляют старый
+  диспетчер работать, а причина видна в `restart.status` = `refused` / `failed`.
+- Если stop-request проигнорирован (зависший хаб), эскалация завершает **только сам pid**
+  (`taskkill` без `/T`): стенды Kestrel и локальный агент — дочерние процессы хаба и не
+  должны умирать вместе с ним. Перед эскалацией личность процесса подтверждается у ОС
+  (время создания процесса против записанного в файле состояния; маркер в командной
+  строке — только когда время создания получить нельзя). Не подтверждено — не убиваем,
+  отдаём «остановите вручную».
+- Сессия переезжает одноразовым файлом передачи (TTL 3 минуты, удаляется при чтении),
+  не аргументом командной строки. Открытая вкладка переподключается сама.
+- Запуск ярлыка «от имени администратора» при живом неэлевированном экземпляре идёт тем
+  же путём перехвата (stop-request, строгий bind).
+- Перезапуск учитывает поставку: во frozen-сборке (`BPMkit-hub.exe`) запускается
+  `sys.executable`, в режиме `--desktop` новый процесс открывает своё окно, а старое
+  закрывается по stop-request. Передаются `--host`/`--insecure`, абсолютный `--config`.
+- Права держатся до выхода диспетчера; обратного перехвата (elevated уступает обычному) нет.
+
+### 3. Однократная операция с правами (П2)
+
+`POST /api/hub/elevated-op {stand, action}` запускает через UAC тот же исполняемый файл в
+режиме `--elevated-op start|stop|restart --stand <имя> --result-file <путь>`: одна операция
+над стендом `host_kind=iis`, без HTTP-сервера, мьютекса и файла состояния, результат в файл,
+выход. Диспетчер остаётся без прав. `GET /api/hub/elevated-op/<op_id>` —
+`pending` / `ok` / `error` / `refused` / `expired`. Одна активная операция на стенд.
+
+### 4. Повышение под другой учётной записью — отказ с пояснением
+
+Если окно UAC подтвердил другой пользователь (over-the-shoulder), у нового процесса другой
+профиль: другой `projects.json`, конфиг, ключи. Работать от его имени — значит молча
+показать пустой реестр или чужие секреты. Новый процесс сравнивает SID своего токена с
+`--initiator-sid` и при расхождении ничего не делает, записывая текст: «Права подтверждены
+другой учётной записью (…). Диспетчер работает с реестром стендов и ключами текущего
+пользователя Windows, поэтому повышение под другой учётной записью не поддерживается. …»
+
+### 5. Мьютекс диспетчера
+
+Именованный мьютекс (GAP-229/284) берётся после bind. Созданный elevated-процессом объект
+получил бы DACL «только администраторы», и неэлевированный установщик BPMkit не увидел бы
+работающий диспетчер. Поэтому мьютекс создаётся с явным security descriptor
+(SYSTEM, Администраторы, текущий пользователь — полный доступ; Everyone — SYNCHRONIZE).
+
+## Модель угроз
+
+- Сторонний сайт не может запросить UAC или операцию: все новые мутации — `POST` с
+  CSRF-заголовком, локальным `Origin` и сессионным токеном; `stand`/`action`/`op_id`
+  валидируются белыми списками и регулярными выражениями.
+- **UAC — не граница безопасности** (позиция Microsoft). Процесс той же учётной записи
+  без прав может править конфиг и реестр стендов, которые затем прочитает elevated-процесс.
+  Мы это принимаем: согласие в окне UAC даётся на диспетчер, работающий с данными этого
+  пользователя. Что сделано против дешёвых приёмов: elevated-процесс не пишет в `run_dir`
+  и не читает оттуда, если путь или файл — reparse point/symlink; временные файлы — со
+  случайным именем и `O_EXCL`; однократная операция повторно проверяет `host_kind=iis`.
+- Права `0o600` на Windows ACL не задают — защиту файла передачи обеспечивает ACL профиля.
+  `run_dir` вне профиля пользователя даёт предупреждение в логе.
+
+## Последствия
+
+- Ошибка прав для IIS решается кнопкой в два клика и видна до первой неудачной операции.
+- Отказ в UAC, чужая учётка, зависший старый процесс — у каждого свой понятный исход,
+  пользователь не остаётся без диспетчера.
+- Живая приёмка возможна только на Windows с IIS и настоящим окном UAC; юнит-тесты
+  покрывают протокол, но не WinAPI.
+
+## Альтернативы, которые не выбрали
+
+- **Только однократная операция на каждое действие.** Минимальные права, но окно UAC на
+  каждый старт/стоп в ежедневной работе неприемлемо — оставлена как дополнительный путь (П2).
+- **Галка «Запуск от имени администратора» в свойствах ярлыка.** Лечит только будущие
+  запуски, не ситуацию «диспетчер уже открыт». Осталась рекомендацией в HOSTING.md.
+- **Задача планировщика «с наивысшими правами» из установщика.** Отклонена владельцем
+  14.09.2026 как избыточная.
+- **Служба Windows.** Другой класс задачи (автозапуск, своя учётка); для удалённых
+  IIS-стендов вопрос остаётся открытым в dev-репо (GAP-282, §3.1 записки).