@oeronteros-1/opencode-orchestra 1.0.28 → 1.0.30

package/README.md

@@ -14,12 +14,21 @@
 - диагностика `doctor`, проверка обновлений и shell completion;
 - идемпотентная установка без удаления пользовательской OpenCode/MCP-конфигурации.
 
-Версия плагина — **1.0.25**. Полный контракт конфигурации описан в [schema/opencode-orchestra.schema.json](schema/opencode-orchestra.schema.json), рабочий пример — в [examples/.opencode/orchestra.jsonc](examples/.opencode/orchestra.jsonc).
+Версия плагина — **1.0.27**. Полный контракт конфигурации описан в [schema/opencode-orchestra.schema.json](schema/opencode-orchestra.schema.json), рабочий пример — в [examples/.opencode/orchestra.jsonc](examples/.opencode/orchestra.jsonc).
 
 ## Что нового в 1.0.9–1.0.25
 
 Полноценные разделы с примерами для пользователей.
 
+### 1.0.29 — надёжность и прозрачная маршрутизация (next/unreleased)
+
+- **Graceful degradation при невалидном `orchestra.jsonc`**: если глобальный или проектный конфиг не парсится либо не проходит валидацию схемы, плагин продолжает запуск на безопасных default-значениях, пишет один warning с путём к конфигу и sanitized-причиной и **не перезаписывает** файл. Обнаружение моделей, регистрация проектов, телеметрия и создание агентов/инструментов продолжаются как обычно.
+- **Структурированная причина маршрутизации**: `orchestra_route` возвращает `routing.lead.model` вместе с машиночитаемым `routing.lead.reason` (`code`, `text`, `matchedCapabilities`, `score`, `budget`) и `routing.source` (`exact_override`, `manual_pool`, `auto_discovered`, `budget_exclusion`, `no_candidate`). `code` — стабильный идентификатор решения; `text` — диагностическая строка без секретов и промптов.
+- **Политика ошибок и capability-aware fallback**: retryable-ошибки (rate-limit/429, timeout/408, provider 5xx/overloaded) переключают на следующий совместимый кандидат; terminal-ошибки (auth/401/403, invalid-request/400/404, неизвестная) останавливают цепочку. Альтернативы фильтруются по capability и бюджету и ранжируются детерминированно: compatibility → priority → tier → бюджетный класс стоимости → id. Плагин **не перехватывает** provider retry: цепочка `fallback.chains` передаётся только для dispatch-failover через `orch-lead`.
+- **События надёжности (reliability events)**: ledger записывает sanitized-события `failed`/`retried` только из реально наблюдаемых попыток (модель, класс ошибки, следующая модель, номер попытки, исход). Сырой текст ошибки не сохраняется; список ограничен последними 100 событиями.
+- **Routing-проверки `doctor`**: неразрушающие проверки для lead/judge/workers, точных overrides, дубликатов и неизвестных цен (предупреждение, никогда не `free`). Валидный частичный конфиг не считается ошибкой.
+- **Карта конфликтов и сохранённые worktrees**: `orch-integrator` строит детерминированную cross-editor карту конфликтов (`editors`, `conflictingPaths`, `ownershipViolations`, `order`, `clean`), работает fail-closed при любом нарушении ownership/ancestry/git-конфликте и сохраняет worktrees для диагностики.
+
 ### 1.0.24–1.0.25 — параллельные редакторы и Windows-совместимость
 
 - **Параллельные редакторы**: `orchestration.parallelEditors` включает безопасный fan-out/fan-in для правок: каждый `orch-editor` работает в отдельном experimental Git worktree, а `orch-integrator` проверяет фактический diff и интегрирует коммиты в детерминированном порядке. При конфликте worktrees сохраняются для диагностики; `0` (по умолчанию) отключает режим.
@@ -254,6 +263,75 @@ bunx @oeronteros-1/opencode-orchestra@latest completion zsh > ~/.zsh/completions
 
 Resolver формирует упорядоченный список fallback-кандидатов из доступных пользователю моделей, предпочитая схожую стоимость и совместимые capabilities. Цепочка передаётся lead в поле `fallback`; execution-слой может переключиться на следующий кандидат при ошибке провайдера. Если текущая версия OpenCode не предоставляет provider-interception, сам плагин не перехватывает вызов и не обещает автоматический retry. Прогноз стоимости — информативное поле: выполнение не блокируется, а предупреждение помогает подтвердить расходы заранее.
 
+### Структурированная причина маршрутизации
+
+`orchestra_route` возвращает `routing` с выбранной моделью lead и машиночитаемой причиной вместо необходимости разбирать прозу:
+
+```jsonc
+{
+  "routing": {
+    "lead": {
+      "model": "anthropic/claude-sonnet-4-5",
+      "reason": {
+        "code": "capability_match",
+        "text": "id=anthropic/claude-sonnet-4-5 cost=subscription capability=explicit score=100",
+        "matchedCapabilities": ["reasoning"],
+        "score": 100,
+        "budget": "balanced"
+      }
+    },
+    "source": "manual_pool",
+    "budget": "balanced"
+  }
+}
+```
+
+- `code` — стабильный идентификатор решения: `frontier`, `preferred_tier`, `preferred_cost`, `capability_match`, `price`, `priority`, `exact_override`. Это машиночитаемый контракт; `text` — диагностическая строка, не являющаяся контрактом совместимости.
+- `matchedCapabilities` — capability, по которым модель подошла (пусто для `exact_override`); `score` — итоговый скоринг победителя; `budget` — режим бюджета.
+- `text` не содержит секретов, промптов, токенов и содержимого файлов.
+
+`source` показывает происхождение выбора: `exact_override` (точное `models.agents["orch-lead"]`), `manual_pool` (ручной пул при `strategy: "manual"`), `auto_discovered` (автособранный пул подключённых моделей), `budget_exclusion` (пул заблокирован бюджетом/лимитом платных вызовов) и `no_candidate` (пул пуст — используется текущая модель OpenCode).
+
+### Политика ошибок
+
+Ошибки классифицируются по policy-классам, а не по сырому тексту:
+
+| Класс | Политика |
+| --- | --- |
+| Rate limit / 429 | переключиться на следующий совместимый кандидат |
+| Timeout / 408 | переключиться на следующий совместимый кандидат |
+| Provider 5xx / overloaded | переключиться на следующий совместимый кандидат |
+| Auth / 401 / 403 | остановиться — ошибка конфигурации |
+| Invalid request / 400 / 404 / unsupported capability | остановиться — ошибка маршрутизации или запроса |
+| Неизвестная ошибка | остановиться, если явно не классифицирована как retryable |
+
+Каждая последовательность ограничена максимальным числом попыток, не повторяет одну и ту же модель и сохраняет исходную ошибку. Лимиты платных вызовов остаются авторитетными.
+
+### Capability-aware fallback
+
+Fallback-цепочка строится только из worker-пулов (`code`, `reasoning`, `research`, `vision`, `image`). Кандидаты фильтруются по budget-eligibility (платные исключаются при исчерпании лимита), а явно несовместимые с требуемой capability отсеиваются до выбора победителя. Неизвестные по capability модели остаются в цепочке, но ранжируются ниже. Альтернативы упорядочиваются детерминированно: compatibility → priority → tier → бюджетный класс стоимости → id. `fallback.chains` в ответе `orchestra_route` содержит `enabled`, `maxRetries` и усечённую до `maxRetries + 1` цепочку на каждую capability. Плагин не перехватывает вызовы провайдера: цепочка предназначена для безопасного dispatch-failover через `orch-lead`.
+
+### События надёжности
+
+Там, где Orchestra может наблюдать выполнение, ledger записывает событие надёжности только из реально наблюдаемых попыток: `attempt`, `model`, `errorKind` (policy-класс, не сырой текст), `outcome` (`failed`/`retried`/`succeeded`), `nextModel` и `at`. Переход `retried` фиксируется только при последующей наблюдаемой попытке после retryable-ошибки; события ограничены последними 100, строки обрезаются, а неопознанные записи отбрасываются. Креды, промпты и тела ответов провайдера никогда не сохраняются. Если вызовы провайдера перехватить нельзя, эквивалентные policy-метаданные возвращаются в `orch-lead`, но фейковое событие выполнения не записывается.
+
+### Routing-проверки `doctor`
+
+`doctor` добавляет неразрушающие routing-проверки с стабильными идентификаторами и severity:
+
+- пустой пул роли — `info` («текущая модель OpenCode»);
+- недоступный точный agent override или невалидный формат `provider/model` — `warning`;
+- роль без совместимого кандидата или заблокированная бюджетом — `warning`;
+- дубликаты кандидатов — `warning`;
+- неизвестная цена победителя — `warning` (никогда не трактуется как `free`);
+- валидный частичный конфиг (пустые пулы, отсутствующие секции) не считается ошибкой и не блокирует запуск.
+
+Проверки не изменяют файлы конфигурации.
+
+### Карта конфликтов и сохранённые worktrees
+
+Перед интеграцией `orch-integrator` выводит фактические изменённые пути из git и строит cross-editor карту конфликтов: `editors` (id, commit, изменённые пути, ownership-нарушения), `conflictingPaths` (пути, затронутые более чем одним редактором), `ownershipViolations`, детерминированный `order` интеграции и флаг `clean`. Любое нарушение ownership, провал ancestry-проверки или git-конфликт останавливает автоматическую интеграцию — интегратор интегрирует всё или ничего и **сохраняет worktrees** для диагностики. Чистый текстовый merge не считается доказательством семантической корректности.
+
 ## Агенты и команды
 
 Плагин добавляет один публичный primary-агент `orch-lead`, скрытых workers, скрытый reduce-агент `orch-merge` и скрытый `orch-judge`. Workers не могут редактировать файлы или делегировать работу дальше; lead может вызывать только агентов Orchestra, после чего сам реализует изменения и проверяет результат.