[2026-09-26] eagle: personal/plans/balda-mm-phase4-agents.md personal/projects/balda/balda-kraken-mm-deploy.md personal/tech/balda-go-fx-pitfalls.md

personal/tech/balda-go-fx-pitfalls.md

@@ -15,6 +15,11 @@
 > **🔴 замкнутый круг привязки при занятом binding** (§«Дефект 8»).
 > 🔴 **Новое в этой сессии:** §«Mattermost Team Edition: что недоступно» — push невозможен.
 > Уточнён §«авторизация — ОДИН механизм»: челлендж НЕ был причиной №1, им был `bad_seq`.
+> 🔴 **Добавлено 2026-09-26 (сессия MCP-фикса):** §«Scope-классификатор нового транспорта» —
+> написать мало, надо зарегистрировать в ДВУХ картах (`app.go` + `preflight.go`); смежное —
+> `balda.session_memory` vs `balda.memory`, MCP через секцию провайдера.
+> §«Сброс падающих тестов» — сначала `git stash`, потом слово «регрессия»;
+> `buildx` без `--load` не кладёт образ в `docker images`.
 > Зеркало секции скилла `devops/docker-balda-service`, добавленной 2026-09-26.
 > Источник: работа над Mattermost-адаптером Балды (Фаза 2) + деплой на Kraken (Фаза 3).
 > Проектные доки: [[personal/projects/balda/balda-mattermost-connector]],
@@ -114,6 +119,94 @@ case transportMattermost:
 
 ---
 
+## 🔴🔴 Scope-классификатор нового транспорта: написать мало — надо зарегистрировать в ДВУХ картах
+
+Найдено 2026-09-26 (Балда на Kraken, MCP-инструменты не подключались). Класс ошибки:
+**функция есть, регистрации нет** — код компилируется, тесты зелёные, отказ виден только в рантайме.
+
+**Симптом:** MCP-инструменты не подключаются к сессии. В чате — «namespace `<name>`
+не подключён к сессии», в логе `function_call_part_count: 0` (модель не вызвала инструмент).
+При включённом `session_memory` сброс сессии падает:
+
+```
+warn … "observe reset boundary: no session-memory classifier is registered for \"mattermost\""
+→ в чате: "Could not reset this session."
+```
+
+**Причина:** `sessionmemoryapp.ScopeResolver` собирается из карты классификаторов по
+`channelType`. Новый транспорт (для Mattermost — коннектор писал Alex) имел
+`ClassifyLocatorScope` в `channel/mattermost/locator_codec.go`, но **не был добавлен
+в карту**. Резолвер fail-closed: `classifier == nil` → `CodeUnsupportedScope`
+(`sessionmemoryapp/capture.go:68-75`).
+
+🔴 **Карт ДВЕ, править обе:**
+- `internal/apps/balda/app.go` — рантайм-граф
+- `internal/apps/balda/preflight.go` — граф валидации
+
+Расхождение между ними даёт «конфиг прошёл preflight, но упал в рантайме» (и наоборот).
+
+```go
+sessionmemoryapp.NewScopeResolver(map[string]sessionmemoryapp.ScopeClassifier{
+    baldatelegram.ChannelType:   baldatelegram.ClassifyLocatorScope,
+    baldaslackagent.ChannelType: baldaslackagent.ClassifyLocatorScope,
+    baldazulip.ChannelType:      baldazulip.ClassifyLocatorScope,
+    baldamattermost.ChannelType: baldamattermost.ClassifyLocatorScope,  // ← добавить
+})
+```
+
+⚠️ Побочный эффект импорта с алиасом: если пакет уже импортировался без алиаса
+(`"…/channel/mattermost"`), все обращения вида `mattermost.X` в файле надо перевести
+на `baldamattermost.X` — иначе `undefined: mattermost` (как в §«Дефект 3»).
+
+📌 **Добавлять в чек-лист нового транспорта** (продолжение списка из 12 пунктов выше):
+13. 🔴 `ClassifyLocatorScope` зарегистрирован в карте `ScopeResolver` **в обоих** файлах —
+    `app.go` и `preflight.go`.
+
+### Смежное: `session_memory` — выключатель MCP-биндера, и это НЕ `memory`
+
+```go
+// app.go:275-278 — выключатель
+fx.Annotate(func() bool { return cfg.Balda.SessionMemory.Enabled },
+    fx.ResultTags(`name:"balda_session_memory_enabled"`))
+// sessionapp/module.go:191-196 — биндер MCP
+func(broker *sessionmemorymcp.ContextBroker, enabled bool) baldaagent.SessionMCPBinder {
+    return SessionMCPBinderAdapter{Broker: broker, Enabled: enabled}
+}
+```
+
+⚠️ **`balda.memory` и `balda.session_memory` — разные секции.** Первая включает память,
+вторая — MCP-биндер сессии. С `memory`-only инструменты в сессию не подключаются.
+
+📌 **MCP-серверы подключаются через секцию ПРОВАЙДЕРА**, не через `balda.mcp_servers`:
+```
+effective = bundled(balda) + runtime.providers.<id>.mcp_servers + balda.mcp_servers
+```
+
+---
+
+## 🔴 Сброс падающих тестов: сначала `git stash`, потом слово «регрессия»
+
+Метод 2026-09-26. `go test -race ./...` на ветке `feat/mattermost-channel` даёт 7 падений
+(`cmd/balda`, `internal/apps/balda`, `mcpruntime`, `session`, тесты layout `sessionmemory`).
+**Ни одно не было регрессией** от правки — те же падения на чистом дереве.
+
+```bash
+git stash
+go test -race ./internal/apps/balda/ ./internal/apps/balda/session/ \
+             ./internal/apps/balda/mcpruntime/ ./cmd/balda/ > /tmp/baseline.log 2>&1
+git stash pop
+# сравнить списки `^--- FAIL` — совпали? значит не регрессия
+```
+
+📌 Объявлять регрессией только то, чего **нет** в baseline. Иначе доклад «я сломал 7 тестов»
+при нетронутом коде.
+
+⚠️ Побочное наблюдение: фоновая сборка `docker buildx build` **без `--load`** кладёт результат
+только в кеш («No output specified with docker-container driver») — образ не появится в
+`docker images`, и последующий `docker save` провалится. Собирать с `--load`.
+
+---
+
 ## 🔴 Прогресс-политика должна совпадать на command- и turn-пути одного транспорта
 
 Найдено 2026-09-26 (сессия PR-подготовки). `handlersfx/mattermost_ingress.go` в