# Balda — актуальный локальный запуск

Execution Broker, Telegram-одобрения и текущая приёмка: [[personal/projects/balda/execution-broker|Execution Broker — текущий локальный контур]].

Broker-кандидат 2026-10-14: `0.1.0-rc.26` / `b64a1ba`, локальные проверки сохранены отдельно. Старая Balda `223b85ad` / `codex/production-readiness` отклонена. Текущая `codex/ingress-outbox-v2` / `085a0d43` синхронизирована merge’ем с upstream `9dcd3660` в `/private/tmp/execution-broker-balda-upstream` (1 behind / 7 ahead после нового QA-only коммита upstream `9cb3c2d7`, конфликтов нет, дерево чистое).

Прежний replay-only фикс Telegram был недостаточен: webhook HTTP 200 предшествует handler. Теперь ответ и recovery-маркеры сохраняются атомарно в SQL, а worker восстанавливает continuation после рестарта без второго update; controls durably допускаются после continuation. Реальный single-update webhook regression с production control publisher прошёл десять failure/restart случаев для callback и текста. Самостоятельно проверен весь diff ветки (58 файлов); прошли финальный полный race-gate, обе storage integration suites, lint/architecture/security/migrations, projection/JetStream/ingress, native macOS MCP scenarios и build. SQLite migration 63 / PostgreSQL migration 28 требуют backup; исторические answered-записи не переигрываются. Полные границы и логи — в карточке выше.

По явному запросу владельца ветка опубликована в `mallexxx/balda`; открыт [upstream PR #52](https://github.com/baldaworks/balda/pull/52), GitHub CI запустился. Изменения не развёрнуты; контейнер `balda-mm-mac` остаётся на прежнем образе. Публикация PR не меняет действующий сервис.

_Проверено: 2026-10-09._

> Это основной runbook для текущей Balda на Mac. Старые документы про `balda-agent-valera-1`, Zulip и Kraken — исторические.

## Текущая схема

- Хост: Mac.
- Контейнер: `balda-mm-mac`.
- Канал: Mattermost.
- Провайдер: Codex ACP.
- Compose: `/Users/admin/Docker/balda-mm-mac/docker-compose.yml`.
- Конфиг: `/Users/admin/Docker/balda-mm-mac/config/config.yaml`.
- Состояние и managed plugins: `/Users/admin/Docker/balda-mm-mac/state`.
- Рабочие каталоги: `/Users/admin/Docker/balda-mm-mac/work`.

Каталоги `config`, `state` и `work` bind-mounted в контейнер. Домашний каталог контейнера хранится в Docker volume `balda_balda-home`.

## Что применять какой командой

| Изменение | Действие |
|---|---|
| Только содержимое `config/config.yaml` | `docker restart balda-mm-mac` |
| `.env`, environment, mounts или service definition в Compose | `docker-compose up -d balda` |
| Новый image/tag | `docker-compose pull && docker-compose up -d balda` |
| Изменение исходного кода | Собрать image, затем `docker-compose up -d balda` |
| Managed plugin | Использовать `/plugin install\|upgrade\|enable\|disable\|remove` |
| Plugin/skill для уже открытой беседы | `/reset` после активации изменения |

`docker restart` перечитывает bind-mounted `config.yaml`, потому что Balda читает его при старте процесса. Он не перечитывает `.env` и не применяет изменения Compose.

Принудительное `--force-recreate` для изменения только `config.yaml` не требуется.

## Plugins и skills

Managed plugin revisions в `state` неизменяемые и проверяются по digest. Их нельзя редактировать вручную в папке. Изменения устанавливаются через команды `/plugin`.

Каталог плагинов обновляется в работающем процессе после install/upgrade/enable/disable/remove. Уже созданная сессия закреплена за старым snapshot, поэтому для неё нужен `/reset`.

Файлы standalone skills редактировать можно, но существующая сессия также увидит новый snapshot только после `/reset`.

## Codex ACP

Актуальный reasoning effort: `medium`.

Codex авторизация хранится в home-volume контейнера. Для headless-входа:

```bash
cd /Users/admin/Docker/balda-mm-mac
docker-compose run --rm --entrypoint codex balda login --device-auth
```

## Obsidian MCP

Codex ACP поддерживает `stdio` и Streamable HTTP. SSE-конфигурация не поддерживается.

```yaml
mcp_servers:
  obsidian:
    type: http
    url: http://host.docker.internal:3101/mcp
    name: obsidian
```

После изменения только этого блока:

```bash
docker restart balda-mm-mac
```

## Проверка

```bash
docker ps --filter name=balda-mm-mac
docker logs --tail 120 balda-mm-mac
```

В логах должны быть успешная инициализация Codex ACP, готовность provider и подключение Mattermost WebSocket.