docs(research): решение и план слияния Hermes Hub → KAgent

Владелец принял направление: один продукт KAgent, функциональность Hermes
переносится нативно, после parity Hermes архивируется. На переходный период
KAgent доделывается на одном сервере, Hermes — на втором.

Ревьюер проверил обе стороны исполнением, а не по аудиту:
- Hermes: CI на main красный; баг pricing fallback реален (safe_dump вместо
  safe_load в telemetry_service.py:164, таблица цен не грузится).
- KAgent (head 131c9b08): лицензии нет; в reasoning-engine/src/server.py
  require_operator_secret стоит на управлении аккаунтами, но НЕ на /v1/execute,
  /v1/decide, /v1/telemetry — расход провайдера открыт без авторизации.
  Поправка к аудиту: последняя активность 18-19 августа, репозиторий замер.

Жёсткий гейт: ключи провайдеров не переезжают в KAgent, пока эти маршруты не
закрыты и это не проверено живым запросом. Сам план миграции положен в
репозиторий как артефакт, чтобы не жил только файлом на столе.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/research/README.md

@@ -16,3 +16,7 @@
   ближайшего архитектурного родственника Hub; что перенять, чего не брать.
 - [scouting-log.md](scouting-log.md) — журнал разведки: что рассмотрено по датам,
   с вердиктом по каждому пункту и причиной.
+- [kagent-merge-decision.md](kagent-merge-decision.md) — решение о слиянии с
+  KAgent: проверенные ревьюером находки, жёсткий гейт на перенос ключей, порядок.
+- [kagent-merge-plan.md](kagent-merge-plan.md) — сам план миграции Hermes → KAgent
+  по фазам, положен в репозиторий как артефакт.

docs/research/kagent-merge-decision.md

@@ -0,0 +1,113 @@
+# Решение: слияние Hermes Hub и KAgent
+
+**Дата:** 2026-09-02.
+**Статус:** направление принято владельцем; исполнение — по условиям ниже.
+**Ревьюер проверил исполнением** обе стороны, насколько имел доступ.
+
+---
+
+## Решение
+
+Вести один продукт — **KAgent** как единую AI-платформу. Функциональность
+Hermes Hub переносится в KAgent нативно, Hermes Hub после достижения parity
+архивируется. Полный план — [kagent-merge-plan.md](kagent-merge-plan.md).
+
+Организация работы на переходный период (решение владельца от 2026-09-02):
+
+- **KAgent** дорабатывается на одном сервере;
+- **Hermes Hub** доводится на втором сервере;
+- после доработки — слияние;
+- **KAgent готовится к слиянию сразу**, с первого дня: контракты и модель
+  безопасности проектируются под будущий перенос, а не подгоняются потом.
+
+---
+
+## Что ревьюер проверил сам, а не взял из аудита
+
+Аудиты — тоже отчёты, поэтому проверены исполнением. Спот-проверка совпала с
+аудитами на конкретных утверждениях — значит доверять им можно, но с поправками
+ниже.
+
+### Hermes Hub
+
+- **CI на `main` красный** — подтверждено, несколько падений 2026-09-02.
+- **Баг pricing fallback реален**: `telemetry_service.py:164` делает
+  `yaml.safe_dump(p.read_text(...))` вместо `safe_load`, затем проверяет
+  `isinstance(data, dict)` — всегда ложно, и `except: pass` это глушит. Таблица
+  цен из `pricing.yaml` не загружается никогда. Аудит: P2. Подтверждено.
+
+### KAgent (репозиторий `ochenstarik-ui/kagent`, head `131c9b08`)
+
+- **Лицензии нет**, репозиторий публичный — подтверждено.
+- **Публичный расход средств подтверждён чтением `services/reasoning-engine/src/server.py`:**
+  функция `require_operator_secret` существует и применяется к управлению
+  аккаунтами (`/v1/accounts`, `pin`, `disable`, `reset-throttle`), но **НЕ**
+  применяется к `/v1/execute`, `/v1/decide`, `/v1/telemetry`, `/v1/models`.
+  `/v1/execute` вызывает `engine.execute(...)` — реальный расход. То есть с
+  подключёнными ключами любой, кто найдёт порт, тратит квоты без авторизации.
+  Это не гипотеза, а код на `main`.
+- **Поправка к аудиту:** аудит датирован 2026-09-02 и говорит об «активности
+  после релиза», но последний push в KAgent — **18–19 августа**, две недели
+  тишины. CI зелёный, но старый. KAgent сейчас не разрабатывается активно. На
+  выводы о коде это не влияет (head-коммит совпал), на планирование сроков —
+  влияет.
+
+---
+
+## Жёсткий гейт (не обсуждается)
+
+**Ни один ключ провайдера не переезжает в KAgent, пока `/v1/execute`,
+`/v1/decide` и `/v1/telemetry` не закрыты авторизацией и это не проверено живым
+запросом.** У владельца ~2 десятка оплаченных аккаунтов. Пока маршруты открыты,
+KAgent небезопасен даже без слияния — это надо чинить в нём независимо.
+
+Это соответствует Phase 0 плана слияния и P0 аудита KAgent.
+
+---
+
+## Порядок, который советует ревьюер
+
+Направление верное — два оркестратора не нужны, Крона не должна знать о Hermes.
+Но последовательность важнее скорости:
+
+1. **Hermes довести до зелёного и стабильного** прежде, чем замораживать. Он —
+   эталон переноса (reference implementation). Сломанный эталон нельзя
+   портировать: parity-тесты будут сверяться с неверным поведением. Сегодня
+   Hermes ещё нестабилен — аккаунты едва работают, `agy`-патч слетает после
+   перезагрузки, `main` красный.
+2. **KAgent Phase 0 (безопасность) — закрыть и проверить исполнением**, начиная
+   ровно с четырёх незакрытых маршрутов. До этого — никаких ключей.
+3. **Контракт выполнения (Phase 1)** можно проектировать уже сейчас, риска нет:
+   `AIExecutionRequest`, `AIExecutionResult`, `ProviderAdapter`, таксономия
+   ошибок, `RoutingDecision`.
+
+## Почему «rewrite не нужен» — неточность
+
+Скелет KAgent есть, но роутер Hermes не портируется построчно: он переезжает в
+другую архитектуру (Rust gateway, TS control plane, Python-сервисы,
+распределённое состояние Redis/Postgres/NATS вместо процесса). Это честный
+rewrite роутера. Сроки планировать от этого.
+
+## Что перенести из Hermes (проверенные тонкости, легко потерять при переносе)
+
+Эти вещи вскрылись только живым прогоном и обязаны попасть в parity-набор:
+
+- вход `agy` читается из `.gemini/antigravity-cli/antigravity-oauth-token`, не из
+  формата Gemini CLI;
+- терминалу входа нельзя подменять `HOME` (X11 берёт ключ из `~/.Xauthority`);
+- `/props` и `/tokenize` у llama.cpp — в корне, не под `/v1`;
+- слот выбирается до входа и не должен плодиться; запрос пути профиля не должен
+  создавать каталог;
+- проверка после подключения не блокирует ответ;
+- честное `Н/Д` с причиной вместо правдоподобных чисел.
+
+Подробности — в [../../agents/](../../agents/) и передаточном брифе.
+
+---
+
+## Координация
+
+Две сессии Claude пишут в один `main` Hermes Hub (сессия на ПК — ревьюер; сессия
+на сервере под `ochenstarik` — исполнитель). Плюс крупный разворот стратегии.
+Обе сессии должны видеть это решение. Перед пушем — `git fetch` и сверка
+`git log --oneline origin/main`.

docs/research/kagent-merge-plan.md

@@ -0,0 +1,107 @@
+# План слияния Hermes Hub → KAgent
+
+Источник — план владельца от 2026-09-02, положен в репозиторий, чтобы не жил
+только файлом на рабочем столе. Оценка и условия исполнения — в
+[kagent-merge-decision.md](kagent-merge-decision.md).
+
+## Цель
+
+KAgent становится единой AI Agent Operating Platform. Функциональность Hermes Hub
+переносится нативно, Hermes Hub и Hermes Agent перестают быть зависимостями,
+Hermes Hub архивируется. Hermes Hub на переходный период — донор функциональности
+и эталон поведения, не встраиваемая библиотека.
+
+## Разделение обязанностей
+
+- **Orchestrator** выбирает агента, workflow, инструменты, контекст, проверку,
+  момент завершения.
+- **AI Router** выбирает провайдера, модель, аккаунт, локально/облако, failover,
+  проверяет квоту, доступность, бюджет, вычислительный узел.
+
+> Orchestrator выбирает агента и задачу. Router выбирает модель, провайдера и
+> аккаунт.
+
+## Что переносится из Hermes
+
+Multi-provider router; адаптеры провайдеров (Antigravity, Claude, Codex,
+DeepSeek, Grok, Local, NVIDIA, Ollama, OpenCode, OpenRouter); менеджер
+аккаунтов/профилей (несколько аккаунтов на провайдера, приоритет, quota,
+cooldown, health, concurrency); health-состояния; quota manager; session
+affinity; lease/concurrency; model registry; capability-routing; локальные
+модели и вычислительные узлы; agent registry (15 ролей как декларативные
+Agent Definition); Dual Coder как workflow; Guardian как policy-слой; Cost
+Controller как системная подсистема; failover-policy с таксономией ошибок;
+telemetry в существующий Observability; audit routing-решений.
+
+## Что НЕ переносить
+
+Hermes-specific bootstrap; дублирующий Web API и отдельный UI; process-local
+архитектуру; JSONL как основное хранилище telemetry; формат настроек Hermes;
+update flow Hermes; роль orchestrator как отдельный runtime; код, привязанный к
+структуре Hermes Agent; compatibility-слои, не нужные после миграции.
+
+Секреты: не переносить хранилище Hermes один-в-один. Порядок — внешний Secret
+Manager → OS/keyring → шифрованное хранение в БД → материализация только на время
+запроса. Запрещено: ключи в обычных JSON, отдача секретов через API, секреты в
+telemetry/audit/трейсах.
+
+## Фазы
+
+- **Phase 0 — Security baseline (блокер).** Auth/RBAC; защита расхода провайдера;
+  service-auth; безопасное хранение секретов; уникальная request identity;
+  реальный E2E. Выход: нет неавторизованного execution и мутаций проекта/задачи;
+  расход защищён; CI зелёный; E2E по настоящему пути зелёный.
+- **Phase 1 — контракты Router.** AIExecutionRequest, AIExecutionResult,
+  ProviderAdapter, Model/Account descriptor, таксономия ошибок, RoutingDecision.
+  Провайдеры пока не переносить. Выход: contract-тесты, fake-адаптер, роутер на
+  тестовых провайдерах.
+- **Phase 2 — Provider SDK.** timeout, cancellation, streaming, маппинг ошибок,
+  usage, cost, health, discovery. Выход: новый провайдер добавляется без правки
+  ядра.
+- **Phase 3 — перенос адаптеров.** Порядок: openai-compatible → Claude →
+  OpenRouter → Google/Antigravity → Grok → DeepSeek → NVIDIA → Ollama → Codex →
+  OpenCode → local. Для каждого: parity, таксономия ошибок, health/auth/
+  streaming/timeout/quota/regression тесты.
+- **Phase 4 — Account Manager.** Безопасные credentials, приоритет, quota,
+  cooldown, health, concurrency, переходы состояний.
+- **Phase 5 — Router Engine.** role/capability routing, scoring, preferred chain,
+  health/quota awareness, same-account и cross-account/provider fallback, session
+  affinity, auto-return primary, failover trace.
+- **Phase 6 — распределённое состояние.** Redis (health, leases, affinity,
+  cooldown), PostgreSQL (providers, accounts, models, policies, budgets, usage,
+  nodes, agents).
+- **Phase 7 — локальные модели / compute nodes.** node agent: регистрация,
+  heartbeat, инвентарь моделей и ресурсов, execution, queue, GPU.
+- **Phase 8 — Agent Registry.** декларативные определения: capabilities, tools,
+  permissions, routing policy, budgets, model constraints.
+- **Phase 9 — Guardian** как policy enforcement: валидация команд, границы ФС,
+  сигналы prompt injection, детект секретов, проверка прав инструментов, сетевая
+  политика, классификация разрушительных действий.
+- **Phase 10 — Cost Controller.** оценочная и фактическая стоимость, жёсткие
+  бюджеты, наследование, cloud/local оптимизация, alerts, kill switch.
+- **Phase 11 — Workflows.** Dual Coder как workflow; шаблоны Coder+Reviewer,
+  Coder+Tester, Security Review, Multi-model Consensus, Local Draft + Cloud
+  Review.
+- **Phase 12 — UI.** разделы Providers, Accounts, Models, Routing, Nodes, Quotas,
+  Budgets, Usage, Health, Agents.
+- **Phase 13 — parity-тесты.** Чек-лист до отключения Hermes: все провайдеры,
+  несколько аккаунтов, quota exhaustion, rate limit, auth failure, failover,
+  локальные модели, session affinity, выбор модели, health, telemetry, Dual
+  Coder, роли.
+- **Phase 14 — decommission Hermes.** запрет новых фич → deprecated → KAgent
+  единственный production path → удаление зависимостей → финальный релиз Hermes →
+  archived.
+
+## Критерий отказа от Hermes
+
+Архивировать только когда KAgent умеет: все нужные облачные провайдеры;
+несколько аккаунтов; локальный AI; авто-выбор модели; failover; учёт quota;
+health; session affinity; telemetry; расчёт cost; роли агентов; эквивалент Dual
+Coder; проверки Guardian; бюджеты; работу на Windows/Linux; полный parity-набор.
+
+## Обязательные P0 KAgent до миграции (из его аудита, часть проверена ревьюером)
+
+Control Plane auth/RBAC (не доверять `x-actor-id`); авторизация
+`/v1/execute` и `/v1/decide` (**подтверждено: сейчас открыты**); уникальная
+request identity; фикс double-consume TOTP; настоящий E2E через Gateway, не mock;
+добавить LICENSE (**подтверждено: отсутствует**).