# Balda 2.0 — Mattermost + распределённое делегирование (план)

> Создан 2026-09-25. Статус: **Фазы 1-3 закрыты 2026-09-26** (MM на Kraken · MM-адаптер
> в коде · оркестратор развёрнут, **бот отвечает в MM**). Фаза 2 выведена на **PR
> `baldaworks/balda#8`** — 8/8 CI PASS, ждёт ревью. Следующая — Фаза 4 (исполнитель).
> Alex дал команду исполнять без вопросов.
> Задача: поднять свежую Балду из `baldaworks/balda` (без наших коммитов), завязать на Mattermost,
> построить распределённое делегирование (дешёвый оркестратор + подписочные CLI в VM).
>
> **Оценка объёма (проверено 2026-09-25):** это ~10-14 рабочих дней, а не «пара вечеров».
> Апстрим переписан полностью (900 файлов), Mattermost-адаптера в нём нет вообще.
> Реалистичная разбивка: MM на Kraken 2-3 ч · MM-адаптер 2-4 дня · оркестратор на Kraken 1-2 дня ·
> исполнитель + мост на Mac 2-3 дня · связка и приёмка 1 день.
>
> **Развилки, решённые Alex 2026-09-26:** бота в MM **не создавать** (токен даст сам);
> вопросов не задавать — решать самостоятельно; команд, требующих подтверждения, не использовать;
> не останавливаться до исполнения. Детали по фазам вынесены в отдельные доки:
> [[personal/projects/balda/mattermost-kraken-deploy]] (Фаза 1) ·
> [[personal/projects/balda/balda-mattermost-connector]] (Фаза 2).
>
> 🔴 **Фаза 4 — план готов, работа НЕ начата: [[personal/plans/balda-mm-phase4-agents]].**
> Решения Alex: папка исполнителя **`~/agents`**, режим **`allow_all`** (full access),
> auth CLI на хосте в **`~/cli-auth`** (вне `~/agents`), управление монтажами — новая
> секция «Agents» в Eagle Dashboard.
> **Проверено живыми тестами:** симлинк в контейнер не проезжает, live `mount --bind`
> на macOS недоступен, шары в контейнер не протянуть → внешние проекты только через
> `-v` + `docker compose up -d`. Разбор — [[personal/tech/macos-docker-virtiofs-mount-limits]].

---

## 0. Ключевые находки разведки (факты, проверено в коде и доках)

### 0.1 Апстрим Балды
- Апстрим переехал: `normahq/balda` → **`baldaworks/balda`**. Релиз: `ghcr.io/baldaworks/balda:latest`, npm `@baldaworks/balda`.
- Наш форк `~/Developer/balda` отстал на **900 файлов** (+135k/−28k строк).
- Архитектура переписана полностью: `handlers/*` → `handlersfx/*`, Zulip вынесен в `internal/apps/balda/channel/zulip/*`, добавлены backoffice (встроенный web UI + админ/логин/аудит), Slack Agent, unified user security state, sessionmemory на Badger.
- Наши коммиты (промежуточные статусы Zulip) в апстрим **не влиты** — `05159d15` есть только у нас.

### 0.2 Mattermost — в апстриме НЕТ
- `grep -i mattermost` по всему `upstream/main` → **0 совпадений**. Ни кода, ни доков.
- Каналы в апстриме: `telegram`, `zulip`, `slackagent`, `webhook` + `channel/router.go`.
- Значит MM = **новый транспортный адаптер**, писать самим.
- Хорошая новость: есть явный контракт для этого — `docs/architecture/transport-presentation-boundary.md`.
  Требование: shared-пакеты владеют семантикой, транспортные пакеты владеют рендерингом/ingress/delivery,
  регистрация через DI в composition root. Образец для копирования: `channel/zulip/adapter.go` (331 стр.) + `client.go` (289 стр.) — по объёму это 2-4 дня работы.

#### MM — это НОВЫЙ chat surface, а не просто «ещё один webhook»
В README апстрима заявлены ровно три chat surface: **Telegram, Zulip, Slack Agent**. MM не входит.
Значит адаптер затрагивает не только `channel/mattermost/*`, но и весь слой, где перечисляются транспорты.
Найденные touchpoints (проверять при реализации):
- `channel/router.go` — регистрация/диспетчеризация транспорта
- `handlersfx/module.go` — composition root (DI-вайринг)
- `internal/apps/balda/state/` — `channel_type` в каноническом locator (`channel_type:address_key`)
- `docs/commands.md` — таблица доступности команд по транспортам (Telegram/Zulip/Slack — колонки)
- `docs/reference/messaging.md`, `docs/architecture/multi-channel-token-auth.md` — контракты auth/доставки

**Следствие:** в MM-адаптере сразу закладывать полный набор: `/start owner=`, `/start invite=`,
`/topic`, `/goalkeeper`, `/auto`, `/reset`, `/skill`, `/cancel`, `/locator`, `/user`.
Scheduler/webhook-таргеты (`balda.scheduler.jobs` → `target: locator`) должны резолвиться в MM-локатор.

### 0.2.1 Что именно есть только у нас (инвентаризация перед «начать с чистого»)

Решение «поднять чистую Балду без наших коммитов» — обосновано. Инвентаризация:

**`~/Developer/balda`** (наши уникальные коммиты):
- `05159d15` — промежуточные статусы Zulip (правит `internal/apps/balda/handlers/balda.go` +25). В `main` нашего форка.
- `bc5fd03c` — то же + Telegram + `messageID` для threading. Лежит на `backup/our-main-before-upstream` и `feat/zulip-transport-intermediate`, в `main` не попала.
- `5ad65955` — **не фича**, а `replace normahq/norma => ./norma-local` в `go.mod`. При переезде удалить.
- `feat/zulip-events-polling` — `c619731d` Events API long-poll + stream_only_with_session фильтр; плюс два коммита про valera Dockerfile/compose.

**`~/Developer/norma-local`** (наши уникальные коммиты):
- `56a6e1e` = `91c2c0a` (дубли) — DeepSeek tool_calls: `pkg/runtime/hostedagent/openai.go` (+286),
  `pkg/runtime/agentfactory/agentfactory.go` (+3), `openai_test.go` (+312).
- **Критично:** в `norma v2` (`f8a7336`) эти файлы **удалены целиком**; модуль стал
  `github.com/normahq/norma/v2`, апстрим использует `github.com/normahq/runtime/v2 v2.0.11`.
  Наш патч не переносится — либо он уже есть в `normahq/runtime/v2`, либо пишется заново.
- `norma-local` отстал от `origin/master` на **26 коммитов** (включая теги `v0.0.11`–`v0.0.13`, `v2.0.0`, `v2.0.1`).

**Проверить перед началом:** есть ли в `normahq/runtime/v2` поддержка tool_calls для OpenAI-совместимых
провайдеров. Если да — наш DeepSeek-фикс не нужен вообще, и потерь нет. Если нет — фикс надо
переписать в новый модуль (см. скилл `adk-hostedagent-openai-mcp`).

### 0.3 Провайдеры Балды (ACP)
Реестр в `cmd/balda/init.go`:

| id | type | model | binary |
|---|---|---|---|
| codex | `codex_acp` | gpt-5-codex | `codex` |
| opencode | `opencode_acp` | opencode/big-pickle | `opencode` |
| copilot | `copilot_acp` | gpt-5-codex | `copilot` |
| gemini | `gemini_acp` | gemini-3-flash-preview | `gemini` |
| claude_code | `claude_code_acp` | claude-sonnet-4-6 | `claude` |

- Балда говорит с CLI через **ACP (Agent Client Protocol)** — через `github.com/normahq/go-adk-acpagent/v2 v2.2.6`.
- Это ровно то, что нужно для «подписочных CLI»: Балда запускает **настоящий** `claude`/`codex` бинарь, а не дёргает API.
- **Мультипровайдерность есть:** несколько провайдеров в `runtime.providers`, переключение через `profiles.<name>.balda.provider`. Но у **одной сессии один провайдер** — переключается профилем, не внутри сессии.

### 0.4 GoalKeeper — уже готовая база для делегирования
- `/goalkeeper <objective>`: цикл work → validate до `verdict: pass` или `max_iterations`.
- Отдельные ADK-сессии для worker и validator (изоляция контекста).
- При workspace mode: изолированный worktree, автогенерация Conventional Commit, squash-merge в `base_branch`, удаление workspace.
- Артефакты в финале: изменённые файлы, ветка, коммит, вывод валидации, next step.
- **Вывод:** это уже «оркестратор + исполнитель», просто оба на одном провайдере.

### 0.5 Auto mode — автономное продолжение
- `/auto on|off` — сессионный режим: после каждого turn планируется внутренний synthetic turn со стирингом.
- Сентинелы `AUTO_DECISION:DONE` / `AUTO_DECISION:WAIT_FOR_USER`.
- Наш прошлый кейс (агент сам не продолжал) — в апстриме закрыт этой фичей.

### 0.6 Юридическая граница по подпискам — КРИТИЧНО
Проверено по официальным докам Anthropic (`code.claude.com/docs/en/legal-and-compliance`) и разбору Zylos (2026-07-13):

**Разрешено:**
- Запуск **немодифицированного** официального бинаря `claude`, залогиненного **под своим** аккаунтом, для своих задач и автоматизации. Claude Code сам является «explicit permission» для автоматизации.
- `claude setup-token` → `CLAUDE_CODE_OAUTH_TOKEN` на headless-машине (Pro/Max). Это документированный путь, не дыра.
- Provisioning своих API-ключей для своих авторизованных пользователей.

**Запрещено:**
- Извлекать OAuth-токен подписки и **переиспользовать его в другом клиенте** (прокси, ре-серв как OpenAI-совместимый API). Anthropic реализовал блокировки на сервере и банит аккаунты. Февраль 2026: OAuth-токены consumer-планов «in any other product, tool, or service — including the Agent SDK» не разрешены.
- Спуфить идентичность клиента Claude Code.

**Следствие для архитектуры:** Балда через ACP = хорошо (запускает настоящий бинарь). Прокси-мост, отдающий подписочный токен наружу как API = бан.
Дополнительно: лимиты Pro/Max рассчитаны на «ordinary, individual usage» — параллельные агенты под одним аккаунтом это серая зона даже с официальным бинарём. Codex CLI от OpenAI в этом смысле либеральнее (инженер OpenAI публично поддержал использование подписочного токена в сторонних харнессах); Gemini CLI — как Anthropic, вплоть до закрытия аккаунта.

---

## 1. Где разворачивать — решение

Требование Alex: постоянная доступность + сборка проектов + подписочные CLI без токенов.

Вывод: **не «или-или», а разделение ролей между двумя контейнерами.**

| Роль | Где | Почему |
|---|---|---|
| Mattermost + оркестратор Балда (DeepSeek) | **Kraken** | 24/7, уже есть docker stack, Zulip-подобный топиковый UX, дешёвый по CPU/RAM |
| Исполнитель (codex/claude CLI по подписке) | **Mac (Eagle)**, в VM | нужен доступ к `~/Developer`, git, тяжёлые сборки; подписка залогинена на маке |

### Почему не всё на Mac
Постоянная доступность Mac не гарантирована (сон, ребуты), а оркестратор должен жить в чате 24/7.

### Почему не всё на Kraken
- RPi5 ARM64: тяжёлые сборки/macOS-таргеты невозможны, `~/Developer` не там.
- Подписочный CLI на Kraken = логин подписного аккаунта на чужом хосте, вне зоны контроля → лишний риск бана.

### Почему VM, а не голый Mac
Изоляция: агент-исполнитель получает полный доступ к файлам и сети. VM даёт откат, снапшоты, ограничение диска. Плюс чистая авторизация (`claude setup-token` внутри VM, вне основного профиля Mac).

### Вариант, который стоит рассмотреть вместо VM
**Одноразовый Docker-контейнер на Mac** (не VM): том с проектом, `CLAUDE_CODE_OAUTH_TOKEN` из env. Плюсы: запуск за минуты, изоляция не хуже, легко убить. Минус: на macOS Docker работает через VM — доступ к хостовому диску только через bind-mount, производительность FS ниже.
**Рекомендация: начать с Docker-контейнера; если понадобится полный desktop/gui или сложный toolchain — переехать в UTM/Parallels VM.** Это на порядок быстрее в запуске.

### Транспорт между оркестратором и исполнителем
- Вариант A: **общий Mattermost-канал** — Балда на Kraken и исполнитель в VM оба боты. Просто, но грязно (лишний шум, конфликты сессий).
- Вариант B: **Мост на Mac**: небольшой сервис (FastAPI), который принимает задачи от Kraken по HTTP/Webhook и запускает CLI внутри. Идемпотентность, очередь, статусы.
- Вариант C: **вторая Балда в VM** и связка через webhooks Балды (в апстриме есть `balda.webhooks.*`).
- **Рекомендация: начать с B**, потому что он не требует ни форка Балды, ни второго канала. Позже можно перейти на C.

✅ **Решено 2026-09-26: вариант B (мост на Mac).** Сетевой путь Kraken → Mac —
**Cloudflare Tunnel** через уже работающий cloudflared на Mac (`agents-bridge.qentra.top`
→ HTTP `localhost:8790` + Access Application), **не WireGuard**: VPS-хаб `91.207.28.205`
удалён 2026-09-01, туннель мёртв. cloudflared-маршруты применяются на стороне Cloudflare
без рестарта процесса. Детали транспорта и монтажей — [[personal/plans/balda-mm-phase4-agents]].
⚠️ hostname обязательно одноуровневый (см. [[personal/tech/cloudflare-tunnel-ssh-published-route]]).

---

## 2. Сценарий делегирования (как это работает для Alex)

```
Mattermost (Alex)
   │  «почини баг X в проекте Y»
   ▼
Балда-оркестратор (Kraken, DeepSeek — дёшево)
   │  1. собирает контекст: читает Obsidian, ищет в web, формирует ТЗ
   │  2. /goalkeeper → цикл work→validate
   │  3. на этапе work вызывает мост → задание в VM
   ▼
Мост (Mac, FastAPI) ──► codex/claude CLI (VM, подписка)
   │                       делает: код, сборка, тесты
   │◄──── возврат: diff, вывод тестов, коммит
   ▼
Балда-оркестратор
   │  4. валидирует результат, обновляет доку в Obsidian,
   │     трекает исполнение, отвечает в Mattermost
   ▼
Mattermost (Alex) — итог + артефакты
```

Ключевое разделение расходов:
- **оркестратор** — DeepSeek (дёшево) — контекст, поиск, документирование, трекинг, коммуникация.
- **исполнитель** — подписочный CLI (фикс-цена) — код, сборка, тесты.

---

## 3. Фазы

### Фаза 0 — подготовка (бэкапы, ~30 мин)
1. `backup/pre-normahq-sync` в `~/Developer/balda` и `~/Developer/norma-local`.
2. Сохранить стэш `whale-20260623` в отдельную ветку (не в stash — стэши теряются).
3. Снять текущий compose Валерии/Клавдия в бэкап (`~/Docker/balda-agent/`, `~/Docker/claudio-agent/`).

### Фаза 1 — Mattermost (Kraken) — ✅ СЕРВЕР РАБОТАЕТ
Детальный док: [[personal/projects/balda/mattermost-kraken-deploy]].

1. ✅ Лицензия — self-hosted **Team Edition** (free).
2. ✅ Развернуть MM на Kraken. **Блокер arm64 найден и решён:** официальный образ
   `mattermost/mattermost-team-edition` — **только amd64**, официальной поддержки arm64 нет.
   **Решение:** свой образ из официального arm64-бинаря `releases.mattermost.com`.
   🔴 **Сборка — НА MAC, не на Kraken** (Alex, 2026-09-26): Mac — тот же arm64 и в 10× быстрее
   (33 с против 346+ с), а buildkit-кэш на Kraken льётся на **SD-карту** (не на data-root).
   Результат: `health=healthy restarts=0`, API `{"status":"OK"}` с Kraken и с Mac по LAN.
3. ✅ Порт **8065**; тома на USB-HDD (`49e8f586…/docker/mattermost`), НЕ на SD.
4. ⛔ **Бота НЕ создавать** — Alex даёт токен сам.
5. ✅ Админ `admin@qentra.top` создан (пароль в `.adminpw`).
6. ✅ **Регистрация закрыта** — проверено живым POST → HTTP 501 `signup_email_disabled`.
7. ✅ CF-маршрут `mm → localhost:8065` добавлен Alex'ом.
8. ✅ **`SITEURL` → `https://mm.qentra.top` — сделано 2026-09-26**: бэкап compose → правка
   скриптом (не sed) → `docker compose up -d` → `healthy restarts=0` (~45 с) → ping через
   туннель `{"status":"OK"}`. ⏳ Осталась приёмка входом в браузере (делает Alex).
   → [[personal/projects/balda/mattermost-kraken-deploy]]

### Фаза 2 — адаптер Mattermost в Балде — ✅ PR ОТКРЫТ: baldaworks/balda#8
Детальный док: [[personal/projects/balda/balda-mattermost-connector]].
PR-план и команды: [[personal/plans/balda-mm-pr-plan]].

1. ✅ Ветка **`feat/mattermost-channel`** от чистого `upstream/main` (`de273d8f`).
2. ✅ Изучен `channel/zulip/*` целиком как образец.
3. ✅ **Написан пакет `channel/mattermost/*`** — 12 файлов, ~2200 строк: client, locator_codec,
   inbound, adapter (все 9 операций), media, ingress (WebSocket), formatting, presentation,
   `mattermostfx/` (4 файла, 7 групп DI).
4. ✅ Shared-слой: `ChannelTypeMattermost`, `TransportMattermost`, `NameMattermostMarkdown`,
   `turncmd.SourceMattermost`, `mattermostfx.Module` в `app.go`.
   ⚠️ `channel/router.go` **не** правился — он map-based (подтверждено).
5. ✅ `go build ./...` = exit 0, `go vet ./...` = exit 0.
6. ✅ **Импорт `mattermostfx` + корневого `mattermost` в `app.go` добавлен** (блокер снят).
7. ✅ **Wiring закрыт:** 5 fx-провайдеров `balda_mattermost_*`, `MattermostConfig` + валидация,
   дефолты в `balda.yaml`, доки `configuration.md`/`commands.md`, проверка канала в `command.go`.
8. ✅ **DI-граф проверен реальным `validateBaldaApplication`** с `mattermost.enabled=true` —
   найдены и починены 3 дефекта (`fx.In` + `fx.ParamTags`, отсутствующие провайдеры строк,
   отсутствующий импорт).
9. ✅ **`golangci-lint` = 0 issues, `go-arch-lint` = OK**, `go build`/`go vet` = exit 0.
10. ✅ **Закоммичено:** `004fda2f feat(mattermost): add Mattermost transport adapter` (40 файлов, +3072).
11. ✅ **PR-проход (2026-09-26):** починены 2 дефекта в коде (идемпотентный
    `MattermostSubject` — из-за него бот не отвечал владельцу; `ProgressPolicy.Typing`),
    написаны **103 новых теста** в 6 файлах, доки README/`docs/balda.md`/`docs/mattermost.md`.
12. ✅ **`tools/` вычищен из ветки** — `/tools/` в `.gitignore` + `git rm -r --cached tools/`
    (коммит `9f1e6c9c`); файлы на диске целы, в PR-diff их нет.
13. ✅ **PR ОТКРЫТ: `baldaworks/balda#8`**, 41 файл, +5622/−18, 7 коммитов.
14. ✅ **CI: 8/8 PASS** на чистом раннере (architecture-lint, lint, test, ingress-e2e,
    jetstream-integration, postgres-integration, sqlite-integration, projection-replay).

**Фаза 2 закрыта на уровне кода и PR.** Осталось: **ревью апстрима + merge**.

📌 **Целевой репозиторий — `baldaworks/balda`.** `origin` = `mallexxx/balda` (форк, родитель
baldaworks), `upstream` = `normahq/balda` = **редирект** на baldaworks (тот же org id).
PR: `gh pr create --repo baldaworks/balda --base main --head mallexxx:feat/mattermost-channel`.

🔴 **Урок PR-прохода:** локальные гейты — необходимое, но **не достаточное** условие. Локально
`cmd/balda` падал на `TestInitCommand_...GeneratesDetectedAgents`, **в CI тот же тест прошёл** —
падение было особенностью машины. В репо есть CI (8 джобов) — **дожидаться его** перед «готово».

#### Дефекты, найденные на этапе закрытия (важно для будущих транспортов)

| # | Дефект | Симптом | Фикс |
|---|---|---|---|
| 1 | `fx.In` внутри `IngressParams` + внешний `fx.ParamTags` | `fx.In structs cannot be annotated with fx.ParamTags` | теги `name:` переехали **в поля структуры**; `NewIngress` без `fx.Annotate` |
| 2 | Нет провайдеров `balda_mattermost_server_url/token/bot_user_id/bot_username` | `missing types: string[name=...]` | 4 `fx.Provide` c `fx.ResultTags` в `app.go` |
| 3 | Валидация стояла в `config.go`, где нет такой функции | якорь не найден | `validateMattermostConfig` в `app.go` рядом с `validateSlackConfig` + вызов после неё |
| 4 | `TestBuiltinRoutes` ждал 4 маршрута | `len(BuiltinRoutes()) = 5, want 4` | добавить маршрут Mattermost в `want` |
| 5 | Мёртвый typing-throttle (`shouldSendTyping`, поля, mutex, `SetTypingThrottleInterval`) | `unused` ×2, затем каскад `undefined` | удалён целиком — `SendTyping` всегда no-op |
| 6 | Обёртка `func(client, logger) *Adapter` без тела | `unlambda` (gocritic) | заменена на `mattermost.NewAdapter` |
| 7 | 🔴 **Двойной префикс `principal`** (`mattermost:mattermost:<id>`) | каждый пост владельца → `settlement_stage=unauthorized`, бот молчит | `MattermostSubject()` сделана **идемпотентной** (срезает префикс) — дефект был «починен» в БД и вернулся |
| 8 | `ProgressPolicy.Typing: true` в command-пути, `false` в inbound | мёртвая ветка + warn-шум | приведено к `false` — у ботов MM нет typing API |

⚠️ **Метод проверки, который окупился:** `go build` ловит только компиляцию. **Реальный DI-граф
валидируется только `validateBaldaApplication` через fx** — именно этот тест нашёл дефекты 1-2,
которых `build`/`vet` не видят. Для любого нового транспорта писать такой тест сразу.
🔴 **Дефект из данных — чинить в коде, а не в БД:** дефект 7 «починили» UPDATE'ом и он вернулся
при следующей записи.

🔴 **Урок Фазы 2:** `go build` = exit 0 **не значит** «транспорт рабочий». fx-несовместимости
и отсутствующие провайдеры видны только при `fx.ValidateApp`/`validateBaldaApplication`.
13 падающих пакетов в апстриме — **предсуществующие**, проверено `git stash`, не наши.

### Фаза 3 — оркестратор на Kraken — ✅ ЗАКРЫТА 2026-09-26 (бот отвечает)
Детальный док: [[personal/projects/balda/balda-kraken-mm-deploy]].
План и разбор причин: [[personal/plans/balda-mm-endtoend-plan]].

**Старт 2026-09-26:** Alex дал команду «разворачивай бота на кракене с привязкой к ММ,
токен deepseek возьми скриптом из hermes whale env, сборка на маке».
⚠️ **Решение «бота не создавать» отменено этой командой.** Бот в MM создан автоматически.

1. ✅ **Бот `balda` создан в MM**, токен проверен `/users/me`, лежит на Kraken (0600).
   `ServiceSettings.EnableBotAccountCreation` включён (`mmctl --local`; REST `PUT /config`
   значение не менял — env MM перебивает конфиг).
2. ✅ **Собран образ на Mac** — из апстримного `Dockerfile.release` (свой писать не пришлось),
   `balda-mm:0.1.1`, linux/arm64, 20.6 МБ, ~110 с. Перенос `docker save | zstd` → `docker load`.
3. ✅ **Развёрнута на Kraken** — `/home/kraken/balda/`, данные на USB-HDD, сеть
   `mattermost_mm-net`, конфиг монтируется в `/workspace/.config/balda/config.yaml`.
4. ✅ **Провайдер DeepSeek** — `type: openai`, ключ из `~/.hermes/hermes-whale/.env` прочитан
   скриптом, в чат не выводился. 🔴 **`base_url` в YAML мёртв** — задавать `OPENAI_BASE_URL`
   в `.env` (см. [[personal/tech/balda-go-fx-pitfalls]] §«Провайдер»).
5. ✅ **WebSocket к MM подключён** — `mattermost websocket connected`, `seq` монотонный.
6. ✅ **Backoffice-админ забутстрапен** (не был в плане, но обязателен — иначе отказ старта).
7. ✅ **Исправлен дефект Фазы 2:** `advertised commands have no actor handler: goal`
   — опечатка в `Advertisement.Names` роняет **весь fx-граф** и даёт crash-loop.
   См. [[personal/tech/balda-go-fx-pitfalls]] §«Дефект 4». Ни один quality gate Фазы 2 его не видел.
8. ✅ **Шесть причин тишины найдены и устранены:** `bad_seq` (WS-пинг без `seq` — MM
   перестаёт пушить события, не разрывая сокет) · `Processor == nil` (MM-хендлера не было
   в DI) · `ChannelMattermost` отсутствовал в `auth` · `/start` отбивался проверкой доступа
   до привязки · `principal` в БД с транспортным префиксом · `base_url` + отсутствие CA
   в `scratch`-образе. Итоговый образ — **`balda-mm:0.1.8`**.
9. ✅ **Верификация пройдена:** бот ответил в канале `balda-test` — `@balda` → `работает`.
   Приёмка выполнена **REST-чтением ленты канала** с проверкой `user_id` автора.
10. 🔴 **Push-уведомления — невозможны на Team Edition.** Диагноз снят и задокументирован
    (официальный прокси требует лицензии; свой MPNS требует своих сборок приложений).
    Безлицензионная альтернатива — SMTP-почта, решение за Alex.

### Фаза 4 — исполнитель в VM/Docker на Mac (~2-3 дня)
0. ✅ **План зафиксирован: [[personal/plans/balda-mm-phase4-agents]].**
   Решения Alex: папка **`~/agents`**, режим **`allow_all`** (full access),
   управление линками — **новая секция «Agents» в Eagle Dashboard**.
   🔴 **Доказано живым тестом: симлинк в Docker НЕ читается** → внешние проекты
   подключать **bind-mount'ом**, не линком. Hardlink — только для файлов внутри
   одного тома (не пересекает ФС, каталоги не линкует).
1. Docker-контейнер (или UTM VM) с Node 24 + `codex` + `claude` + `git`.
2. Авторизация: `claude setup-token` на Mac → `CLAUDE_CODE_OAUTH_TOKEN` в контейнер; для codex — свой flow.
3. Bind-mount проектной директории (не весь `~`).
4. Мост: FastAPI-сервис, принимает задачу от Kraken, запускает CLI headless, возвращает diff/тесты.
5. Идемпотентность + таймауты + лимит параллельных задач (не более 1-2, чтобы не ловить «unusual traffic patterns»).

### Фаза 5 — связка и приёмка
1. Сквозной тест: сообщение в MM → Балда → мост → CLI → результат обратно в MM.
2. Проверить расходы: DeepSeek-токены оркестратора + подписочные лимиты исполнителя.
3. Записать в Obsidian: как работает, где логи, как откатить.

---

## 4. Риски

| Риск | Оценка | Митигация |
|---|---|---|
| Бан подписочного аккаунта за «unusual traffic» | средний | только официальный бинарь; не более 1-2 параллельных задач; не проксировать токен; мониторить письма Anthropic |
| MM-адаптер разъедется с апстримом | высокий | держать как отдельный fork-патч, ребейзить на каждый релиз; либо предложить в апстрим PR |
| Kraken: USB-HDD монтируется ~130 с, есть mount-race | известный | drop-in `RequiresMountsFor` уже применён и проверен reboot'ом; volume не на data-root |
| RPi5 не тянет сборку | **подтверждён** | 🔴 **собирать ЛЮБЫЕ образы для Kraken на Mac, НИКОГДА на Kraken** — buildkit-кэш льётся на SD, плюс 10× медленнее. Перенос `docker save │ zstd` → `ssh kraken 'docker load'`. См. [[personal/projects/balda/mattermost-kraken-deploy]] |
| Mattermost free-лицензия ограничивает нужное | низкий | Team Edition работает; проверено на 11.11.1 |
| 🔴 **Официального arm64-образа MM НЕ существует** | **решён** | свой образ из официального arm64-бинаря; сторонние community-образы не брать. См. [[personal/projects/balda/mattermost-kraken-deploy]] |
| 🔴 **Hermes маскирует секреты в tool-выводе** | **решён (обход найден)** | `write_file` пишет байт-в-байт и **не** редактируется; маскировка только на ЧТЕНИИ (`code_file=True`). Значения не писать литералами — собирать на хосте. См. [[personal/tech/hermes-secret-redaction-bypass]] |
| 🔴 **uid bind-mount конфликт на Kraken** | **подтверждён (2×)** | владелец тома обязан совпадать с uid из образа. `postgres/`→`70:70`, остальное→`2000:2000`. Тот же класс, что crash-loop `hermes-kraken` |

---

## 5. Открытые вопросы к Alex

> ⚠️ **2026-09-26: Alex запретил задавать вопросы** — решения принимать самостоятельно,
> искать в Obsidian, а не спрашивать. Пункты ниже оставлены как история; ответы даны инлайн.

1. **Mattermost:** ✅ self-hosted **Team Edition** (free).
2. **VM vs Docker:** ✅ начинаем с **Docker-контейнера** на Mac.
3. **Kraken:** ✅ на **USB-HDD-разделе**. Диск **не нестабилен** — просто медленно монтируется
   (~130 с, mount-race закрыт drop-in'ом). Минус HDD — 5400rpm, ~95 МБ/с на чтение.
4. **Провайдер оркестратора:** ✅ **DeepSeek**.
5. **Судьба текущей Валеры/Клавдия:** ⏳ отложено — держим параллельно на время миграции.
6. ✅ **Бота в MM не создавать** — токен даст Alex (2026-09-26).
   ⚠️ **ОТМЕНЕНО в тот же день, вечером:** Alex скомандовал «разворачивай бота на кракене
   с привязкой к ММ» → бот `balda` создан автоматически, токен добыт и лежит на Kraken.
   См. [[personal/projects/balda/balda-kraken-mm-deploy]].

---

## 6. Что понадобится прочитать перед реализацией

- `docs/architecture/transport-presentation-boundary.md` — контракт транспортов
- `docs/architecture/runtime-contract.md` — инварианты рантайма
- `docs/reference/configuration.md` — конфиг провайдеров и MCP
- `docs/reference/plugins.md` — расширения
- `docs/goal-workflow.md` — контракт GoalKeeper
- `docs/architecture/auto-mode.md` — автономное продолжение
- `docs/reference/job-runtime.md` — durable jobs, scheduler, webhooks
- `internal/apps/balda/channel/zulip/*` — образец адаптера

## История
- **2026-09-25**: создан по итогам разведки апстрима и юридической проверки подписок.
- **2026-09-25**: добавлена оценка объёма (10-14 дней); уточнено, что диск Kraken НЕ нестабилен
  (только медленный mount ~130 с) — формулировку «диск нестабилен» Alex потребовал удалить из
  доков и памяти. См. `personal/tech/docker-data-root-mount-race.md` §«Диск НЕ нестабилен».
- **2026-09-26**: **старт исполнения.** Решения Alex: бота не создавать, вопросов не задавать,
  подтверждений не использовать, не останавливаться до результата.
  - Фаза 1: найден и решён блокер arm64 (свой образ из официального бинаря), compose+`.env`
    записаны на Kraken, сборка запущена. → [[personal/projects/balda/mattermost-kraken-deploy]]
  - Фаза 2: ветка `feat/mattermost-channel` от чистого `upstream/main`, разведка `channel/zulip/*`
    завершена, архитектура коннектора зафиксирована.
    → [[personal/projects/balda/balda-mattermost-connector]]
  - Побочно: разобран механизм маскировки секретов Hermes и найден обход.
    → [[personal/tech/hermes-secret-redaction-bypass]]
- **2026-09-26 (позже)**: **Фаза 1 ЗАКРЫТА, Фаза 2 — код написан.**
  - Alex потребовал **закрытую регистрацию** в MM — сделано и проверено живым запросом (HTTP 501).
  - Alex указал на ошибку: **сборка на Kraken вместо Mac** → перенесена на Mac (33 с против 346+ с),
    buildkit-кэш на SD больше не растёт. Урок зафиксирован в §Риски.
  - MM на Kraken: `health=healthy restarts=0`, API OK с Kraken и Mac, админ создан.
  - Коннектор: 12 файлов написаны, `go build ./...` = exit 0.
  - Найдены и починены 3 дефекта деплоя: `CMD ["mattermost","server"]`, `--strip-components` в tar,
    двойной uid-конфликт (`postgres/` vs остальное).
  - 🔴 Незакрыто: импорт `mattermostfx` в `app.go` + тесты коннектора.
- **2026-09-26 (вечер)**: **Фаза 1 закрыта полностью, Фаза 2 — блокер сборки снят.**
  - `mm.qentra.top` подтверждён Alex'ом как работающий. `SITEURL` → `https://mm.qentra.top`
    (бэкап compose → скрипт `set-siteurl.py` → `compose up -d` → `healthy restarts=0` →
    ping через туннель OK).
  - Коннектор: импорт `mattermostfx` **и** корневого `mattermost` в `app.go` добавлен →
    `go build ./...` = exit 0.
  - Закрыт весь wiring: `MattermostConfig` + `validateMattermostConfig`, 5 fx-провайдеров
    `balda_mattermost_*`, дефолты в `balda.yaml`, доки `configuration.md` + `commands.md`,
    Mattermost в `validateBaldaChannelConfiguration`.
  - 🔴 **Внедрён метод правок через дельта-апплаер** (`tools/apply-project-deltas.py`) —
    идемпотентные текстовые дельты с якорями вместо sed/in-place.
    → [[personal/projects/balda/balda-mattermost-connector]] §«Метод правок»
  - **Тесты поймали 3 дефекта, которых не видел `go build`:** `fx.In` + внешний
    `fx.ParamTags`, отсутствующие провайдеры зарегистрированных строк, отсутствующий импорт.
    Проверка графа — реальный `validateBaldaApplication`, не компиляция.
  - Внесена 1 регрессия: `TestBuiltinRoutes` ждёт 4 маршрута, в `BuiltinRoutes()` их 5.
    ⚠️ 13 падающих пакетов — **предсуществующий дефект апстрима**, подтверждено `git stash`.
- **2026-09-26 (ночь)**: **Фазы 1 и 2 ЗАКРЫТЫ.**
  - `TestBuiltinRoutes` починен (маршрут Mattermost добавлен в `want`).
  - `golangci-lint` нашёл 4 замечания → исправлены: мёртвый typing-throttle удалён целиком
    (`shouldSendTyping`, поля, mutex, `SetTypingThrottleInterval`) — `SendTyping` у MM всегда no-op;
    `inamedparam` в assertion; неиспользуемые импорты; `unlambda` в `module.go`.
  - `.go-arch-lint.yml` обновлён (по требованию AGENTS.md): компоненты `mattermost_transport`
    и `mattermost_wiring`, право зависимости у `composition_root` и `ingress_wiring`.
  - **Все quality gates зелёные:** `build` 0 · `vet` 0 · `golangci-lint` **0 issues** ·
    `go-arch-lint` **OK** · 3 новых теста PASS.
  - **Закоммичено:** `004fda2f feat(mattermost): add Mattermost transport adapter` (40 файлов, +3072).
- **2026-09-26 (поздний вечер)**: **Старт Фазы 3.** Команда Alex: «разворачивай бота на кракене
  с привязкой к ММ, токен deepseek возьми скриптом из hermes whale env, сборка на маке».
  - ✅ Бот `balda` создан в MM (`user_id=edxrgupoxiyg5gzmr79tjypbme`), токен лежит на Kraken
    в `/home/kraken/balda/secrets/mm-bot-token` (0600), проверен живым `/users/me`.
    ⚠️ Это **отменяет** ранее зафиксированное «бота не создавать».
  - ✅ `ServiceSettings.EnableBotAccountCreation` включён через `mmctl --local`.
  - 🔴 Попутно найдены **три питфолла редакции секретов Hermes** (переменная `TOKEN`,
    литерал заголовка авторизации, `$PW` во вложенном heredoc) — записаны в
    [[personal/tech/hermes-secret-redaction-bypass]].
  - ⏳ Дальше: сборка образа на Mac → деплой → приёмка в UI MM.
    Детальный план: [[personal/projects/balda/balda-kraken-mm-deploy]].
- **2026-09-26 (после приёмки)**: **Разведка под Фазу 4.** Фаза 3 подтверждена закрытой
  (бот отвечает аккаунту Alex, `settlement_stage=accepted`).
  - Alex решил три развилки: папка исполнителя — **`~/agents`**; подтверждения —
    **full access** (`permissions.mode: allow_all`); управление линками — **новая секция
    «Agents» в Eagle Dashboard** (`~/Developer/eagle-dash/`).
  - 🔴 **Живой тест Docker (alpine:3.20 arm64): симлинк в bind-mount НЕ читается** —
    цель резолвится от корня контейнера. Следствие: внешние проекты подключать
    **bind-mount'ом** через манифест `~/Developer/agents-mounts.yaml`, не линком.
    Hardlink каталоги не линкует и ФС не пересекает (`EXDEV`) — только файлы внутри тома.
  - Уточнена система подтверждений: `ask` в Balda поддержан **только** для Telegram и
    Slackagent, для Mattermost фейлится закрыто (`docs/architecture/interactive-questions.md`).
  - План зафиксирован: [[personal/plans/balda-mm-phase4-agents]]. Работа **не начата** —
    ждёт выбора Alex: Шаг 1 (`~/agents` + контейнер) или Шаг 4 (секция в Dashboard).

## Связанные заметки
- [[personal/projects/balda/mattermost-kraken-deploy]] — Фаза 1: MM на Kraken (arm64-блокер, деплой)
- [[personal/projects/balda/balda-mattermost-connector]] — Фаза 2: архитектура MM-коннектора
- [[personal/projects/balda/balda-kraken-mm-deploy]] — Фаза 3: Балда на Kraken + бот MM (план)
- [[personal/tech/balda-go-fx-pitfalls]] — 🔴 fx-питфоллы + метод правок дельтами
- [[personal/tech/hermes-secret-redaction-bypass]] — обход маскировки секретов Hermes
- [[personal/tech/docker-data-root-mount-race]] — mount-race на Kraken (закрыт, reboot-безопасен)
- [[personal/projects/balda/balda-valera]] — текущая эксплуатация Балды/Валеры (форк, старая архитектура)
- [[personal/projects/balda/fast-rlm-integration]] — fast-rlm MCP sidecar (наша ветка)
- [[personal/tech/hermes-fork-vs-upstream]] — аналогичный опыт сравнения форка с апстримом