opencode-orchestrator-uni 0.5.1 → 0.5.2

package/docs/ru/reference.md

@@ -0,0 +1,482 @@
+# Справочник
+
+Подробный справочник комплекта оркестратора: защита записи, пять инструментов,
+протокол сессии, настройка моделей и локали, правила приоритета.
+
+[Назад в README](../../README.ru.md)
+
+Комплект регистрируется при setup через `ctx.agent.transform` /
+`ctx.reference.transform`. Reference `audit-kit` указывает на per-locale каталог
+`docs/<locale>/` пакета; OpenCode перечисляет его как дополнительный локальный
+каталог, поэтому агенты читают `<reference path>/call-mechanics.md` напрямую.
+Поставляются `call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`,
+`instruction-other-session.md`, `context-efficiency.md` и
+`session-discipline.md` — например,
+`<reference path>/process-ready-loop.md`.
+
+## Защита записи
+
+У самого оркестратора `edit` запрещён на `*`. Плоские `permissions` — лишь
+узкий fallback-allowlist для артефактов аудита/состояния, а реальный guard —
+hook `permission.hook("evaluate")` в `lib/write-guard.ts` с path-root
+семантикой.
+
+Аудиторы read-only на уровне инструментов для `edit`/`write`/`patch`
+(`edit: deny`); промпт запрещает остальную запись. Запись через shell (redirect,
+`sed -i`, `tee`) — принятый риск (I-M15), а не песочница.
+
+- Каталог сессии читается на каждое событие (`session.get`), поэтому
+  перемещённая сессия оценивается от нового каталога. При ошибке чтения
+  используется setup-каталог и пишется warning — fail-open.
+- Ресурс вне каталога сессии — deny: guard и есть граница workspace, поэтому
+  `reports/`, `docs/planning/` и `audit-*` вне её не пишутся. Внутри каталога
+  первый **корневой** сегмент решает.
+- `reports/` — зарезервированный artifact-root: всё поддерево доступно для
+  записи (даже `reports/src/x.ts`), поэтому проектный код туда не кладём (путь
+  `packages/reports/**` по контракту тоже считается артефактом).
+  `docs/planning/**/*.md` разрешён (вложенный Markdown на любой глубине; `.ts` —
+  нет). `docs` — отдельная ветвь, не source-root: остальной `docs/**` запрещён.
+- Source-корни (`src`, `lib`, `test`, `tests`, `agents`, `tools`, `schemas`,
+  `eval`, `.github`) запрещены даже под артефактным префиксом
+  (`src/reports/x.ts`, `src/docs/planning/x.md`).
+- Корневые artifact-файлы (`case-*`, `risks-*`, `handoff-*`, `decisions-*`,
+  `state.md`) разрешены только в корне location, под `reports/`,
+  `docs/planning/` или в каталоге `audit-*` — `app/state.md` запрещён.
+- Hook выполняется после плоских правил, поэтому локальный `edit: allow` для
+  `orchestrator` тоже закрыт. Плоский fallback несёт только этот артефактный
+  набор root-правилами (`reports/*`, `case-*.md`, `risks-*.md`, `handoff-*.md`,
+  `decisions-*.md`, `state.md`, `docs/planning/*.md`) плюс `audit-*/…`; широкие
+  `*/state.md`-шаблоны убраны, поэтому `src/state.md` запрещён и без hook, но
+  last-match всё равно не выражает приоритет корней везде
+  (`audit-x/src/case-y.md`) — плагин пишет warning.
+- Fallback уже hook'а для вложенных артефактных корней: `lab/x/reports/*` и
+  подобные пути пишутся только с hook (root-правила покрывают лишь `reports/*`
+  от корня location).
+- Сбой или таймаут чтения сессии (граница 250 мс) даёт fallback на
+  setup-каталог и warning один раз на guard; у перемещённой сессии абсолютный
+  артефакт в новом каталоге тогда может получить deny (fail-closed для этого
+  класса). Один флаг `sessionWarned` без счётчика — принято: сбои после первого
+  warning молчат.
+- `shell` остаётся для git и проверок. Запись через shell и symlink/junction
+  (хост матчит нормализованный лексический путь, а не `realpath`) — принятые
+  риски, как и fail-open (сломанный guard не роняет сессию); ими управляет
+  промпт, а не песочница. Отказ инструмента — это правило роли, правка уходит
+  субагенту.
+
+## Инструменты
+
+Плагин регистрирует пять детерминированных **read-only** инструментов в
+пространстве имён `orch_uni`.
+
+| Имя                        | Read-only | Что делает                                                                    |
+| -------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `orch_uni_validate_report` | да        | Достаёт SGR JSON-блок отчёта, разрешает его схему, валидирует                 |
+| `orch_uni_context_lint`     | да        | Детерминированный аудит AGENTS.md/SPEC.md: бюджет, vague, ссылки, секции       |
+| `orch_uni_snapshot`        | да        | Детерминированная ревизия дерева каталогов (sha256 на файл + агрегатный хэш)  |
+| `orch_uni_sessions`        | да        | Дочерние сессии сессии: агент, модель, стоимость, токены, время               |
+| `orch_uni_session_stats`   | да        | Счётчики протокола сессии: промпт, компакции, тулы/ход, урезанные выводы       |
+
+Каждый инструмент отвечает JSON-текстом. Ошибки — **типизированные коды** внутри
+тела (`E_INPUT`, `E_NO_JSON`, …), а не исключения, чтобы агент мог ветвиться по
+коду, не разбирая прозу. Ни один из пяти ничего не пишет в воркспейс, хранилище
+сессий или конфигурацию.
+
+### `orch_uni_validate_report`
+
+```jsonc
+{ "text": "<текст отчёта>" }              // или
+{ "path": "reports/empiric-r1.md",        // абсолютный или относительно каталога локации
+  "schema": "empiric/v1" }                // опционально: ожидаемый id схемы
+```
+
+Укажите ровно одно из `text` / `path`. Инструмент берёт **последний** fenced-блок ```` ```json ````,
+который парсится и несёт поле `schema`, разрешает схему по этому полю и валидирует документ.
+
+```jsonc
+{ "valid": true, "schema": "empiric/v1", "errors": [], "warnings": [ … ] }
+{ "valid": false, "code": "E_INVALID", "schema": "empiric/v1",
+  "errors": [ { "path": "$.findings[0].severity", "message": "expected one of …" } ],
+  "warnings": [] }
+```
+
+| Код                 | Значение                                                             |
+| ------------------- | -------------------------------------------------------------------- |
+| `E_INPUT`           | Плохой вызов: нет/оба `text`/`path`, неверные типы, нечитаемый файл   |
+| `E_NO_JSON`         | Fenced-блок ```` ```json ```` не найден                              |
+| `E_PARSE`           | Блок есть, но ни один не парсится как JSON                           |
+| `E_UNKNOWN_SCHEMA`  | Отчёт называет id, которого нет в комплекте (или не называет вовсе)   |
+| `E_SCHEMA_MISMATCH` | Отчёт называет схему, отличную от ожидаемой                          |
+| `E_INVALID`         | Документ не удовлетворяет своей схеме (см. `errors`)                 |
+| `E_SCHEMA_IO`       | Схемы комплекта недоступны или битые (см. `directory`, `file`)       |
+| `E_ABORTED`         | Сессия остановлена во время чтения отчёта                            |
+
+`warnings` несут правила промпта, которые *структурно валидный* отчёт всё ещё
+может нарушить — то, что JSON Schema выразить не может: отсутствующий `rc` у
+claim'а `empiric` с `method` = `run|measure|compare_base`, элементы `self_check`
+вне 1–19, инвариант `invariant`, помеченный `violated` без контрпримера,
+непокрытая обязательная строка `lines_checked`, расхождение `verdict` и `gate` у
+`meta`, инварианты `closing_list`/`verdict` у `redteam`.
+
+Схемы лежат в `schemas/*.json` и выведены **строго** из SGR-секций
+`agents/*.md`, которые остаются источником истины: тестовый набор парсит
+SGR-шаблон каждого агента и падает, когда поле промпта или значение enum не
+принимается его схемой. `context-lint-failure/v1` — типизированный конверт ошибки
+`orch_uni_context_lint`: у него нет шаблона агента, и отчётом он не является. Схемы
+разрешают `additionalProperties` — агенты могут
+добавлять свои поля (`verdict_label`, `check`, …).
+
+### `orch_uni_context_lint`
+
+```jsonc
+{ "path": "AGENTS.md" }                  // файл или каталог, относительно локации
+{ "path": ".", "max_lines": 150, "max_tokens": 2000 }
+{ "path": ".", "max_words": 2000 }       // бюджет слов SPEC; по умолчанию 1500 (цель), потолок 2000
+{ "path": ".", "max_file_bytes": 500000, "max_files": 100, "max_findings": 50, "max_total_findings": 500 }
+```
+
+Детерминированный read-only аудит `AGENTS.md`, `SPEC.md` и `CLAUDE.md`. Возвращает
+`{ schema: "context-lint/v1", ok: true, verdict, closing_list, files, summary, truncated? }`;
+каждая находка несёт `id`, `severity`, `kind`, `evidence`, `detail` и `fix`. Проверки:
+бюджет строк/токенов/слов, различные vague-фразы, дубли строк, битые относительные ссылки,
+плейсхолдеры, даты/версии в первых трёх строках, обязательные секции и колонка Test
+у AC. Ссылки и явные цели ограничены **реальным** путём: symlink/junction, ведущий за
+пределы корня, пропускается, а такая цель отклоняется (`E_OUT_OF_ROOT`). Код-фенсы,
+inline-код и HTML-комментарии маскируются: пример не считается правилом — структурные
+проверки (команды, границы, проверка) читают полную маску, а требования, AC-id и
+non-goals — маску фенсов. Цели ссылок передаются из построчного сканера по одной
+(массива кандидатов нет), поэтому память не растёт с числом ссылок; проверки ограничены
+на файл 50 000 кандидатами, сигнал проверяется на каждой строке и каждые 100 кандидатов,
+а кэши ссылок держат не более 5 000 записей, поэтому abort срабатывает; 2001 ссылка
+проверяется обычным образом, 50 000 валидных ссылок дают pass, а 50 001-й кандидат делает
+список неполным (`truncated: true` плюс MAJOR-маркер `link candidates truncated` в
+`closing_list`), он не может дать pass.
+Отдельного потолка на
+битые ссылки нет: вывод ограничивают общие лимиты находок, а переполнение помечается.
+Строка сканируется любой длины: сканер ссылок и регулярное выражение плейсхолдеров линейны,
+поэтому 4100-символьная строка проверяется как любая другая, а битая ссылка или
+плейсхолдер на ней — настоящая находка, а не маркер. Внутреннего потолка дублей нет. Цели
+UNC/сетевые пути никогда не пробуются. Замер (bun 1.4.2, Windows, свежий процесс):
+50 001 битая ссылка с `max_findings: 2` → ~1,4 с и ~67 МБ пикового RSS; 50 тыс.
+обычных строк → ~0,14 с / ~65 МБ; одна строка 2 МБ со ссылками → ~3,1 с / ~116 МБ
+(~41 МБ без ссылок). Маскирование переиспользует строку как есть, если в ней нет
+backtick и `<pre>`/`<code>`/`<!--`, поэтому не копирует строку посимвольно, а строка
+в 2 МБ остаётся ограниченной 50 000 кандидатами, а не материализует все ссылки.
+Лимиты: ≤ 2 МБ на файл, ≤ 500 файлов за прогон. `max_findings` (на файл) — это N на
+severity: сохраняются до N MAJOR и N MINOR/INFO, излишек заменяется одним маркером
+(MAJOR, если выпал MAJOR, иначе INFO); MAJOR-маркер остаётся в `closing_list`.
+`max_total_findings` (глобально, по умолчанию 1000)
+сохраняет сначала MAJOR; при переполнении MAJOR остаются `max_total` находок плюс один
+MAJOR-маркер `truncated`. Усечённый список помечается `truncated: true`, а не скрывается.
+Маркеры дополнительны к `max_findings` и не расходуют его бюджет: маркер усечённых
+кандидатов-ссылок и маркер усечённых находок дают по маркеру в одном прогоне, поэтому
+`max_findings: 2` на 20 001 битой ссылке даёт 2 сохранённые находки плюс 2 маркера. Маркеры
+указывают на `file:1` в `evidence`.
+Non-goals считаются как элементы верхнего уровня: перенесённый абзац — один элемент,
+inline `;`/`,`/`and`/`и` делят только верхний уровень (не внутри `(…)`, `[…]`, бэктиков
+любой длины или `<code>`), а bullet с отступом 0–4 пробела под лейблом — элемент; фенсы,
+`<pre>` и код с большим отступом — нет.
+Плейсхолдеры — `<...>` (три и более точки) и `TODO`/`TBD`/`FIXME`; `<DoD>` и
+`<name>` — разметка.
+`max_lines` — единственный бюджет корня (200 строк), который применяет инструмент;
+цифры 60/200/100 по уровням в [`docs/`](../) — ориентир для авторов, а не отдельные
+лимиты инструмента. `max_words` по умолчанию равен цели 1500 слов SPEC; передайте
+`max_words: 2000`, чтобы применять документированный потолок. Типизированные ошибки: `E_INPUT`, `E_NOT_FOUND`, `E_NO_FILES`,
+`E_IO`, `E_ABORTED`, `E_LIMIT_FILE`, `E_LIMIT_FILES`, `E_OUT_OF_ROOT`.
+Ошибка — типизированный payload `{schema:"context-lint-failure/v1", ok:false, code, message, path?, bytes?, files?, max?}`,
+который валидируется только по `context-lint-failure/v1`; отчёт —
+`{schema:"context-lint/v1", ok, verdict, closing_list, files, summary, truncated?}`, и каждый файл несёт `lines`,
+`words`, `chars` и `tokens_est` (токены оцениваются как кириллица/3 + прочее/4). Каталог
+сканируется до глубины 3, а `max_files` отказывает рано: обход останавливается на первом файле
+выше лимита. Ничего не пропадает молча: каталог ниже лимита глубины, ссылка или junction вне
+корня workspace и незакрытые fence, `<pre>` или HTML-комментарий дают INFO-находки, поэтому `pass`
+не скрывает непроверенную область. Незакрытый `<code>` — строчная маска: он скрывает
+остаток своей строки и не репортится (INFO дают только fence, `<pre>` и HTML-комментарий,
+которые тянутся через строки). Отмена наблюдается между файлами, каждые 2048 строк
+построчной проверки и в каждом гейте, поэтому худшая латентность — один проход маски по
+файлу под `max_file_bytes` (десятки мс на 2 МБ), а не весь скан. Команды считаются только в коде, таблице задач или секции
+Commands, HTML-комментарий вроде `<!-- npm install -->` командой не является, а `make` требует
+цели, поэтому проза «Make sure …» — не команда. Скан от корня подхватывает и фикстуры вроде
+`eval/`; передайте явный путь, если нужны только канонические файлы.
+
+### `orch_uni_snapshot`
+
+```jsonc
+{ "path": "lab/stack-test", "exclude": ["tmp"] }   // exclude опционален и аддитивен
+```
+
+```jsonc
+{ "root": "C:\\…\\lab\\stack-test",
+  "files": [ { "path": "a.txt", "sha256": "…", "bytes": 1 } ],
+  "aggregate": "…" }
+```
+
+- `aggregate = sha256` по отсортированным строкам `"<relpath>\0<sha256>\n"`
+  (разделители `/`, порядок кодпойнтов) — стабилен между прогонами, машинами и
+  порядком обхода и меняется, когда меняется путь или содержимое любого файла.
+- По умолчанию (всегда) исключены: `node_modules`, `.git`, `.ae`; `exclude`
+  добавляет имена, целые относительные пути или относительные префиксы
+  (`lab/tmp`). Симлинки пропускаются.
+- Лимиты: ≤ 5000 файлов, ≤ 50 МиБ на файл — `E_LIMIT_FILES` / `E_LIMIT_BYTES`
+  (падает весь снапшот; усечённый снапшот дал бы неверный агрегат). `E_NOT_FOUND`
+  для отсутствующего пути или не-каталога, `E_ABORTED`, когда сессия остановлена.
+
+### `orch_uni_sessions`
+
+```jsonc
+{}                                           // дети вызывающей сессии
+{ "sessionID": "ses_…", "recursive": true }  // всё поддерево другой сессии
+```
+
+```jsonc
+{ "sessionID": "ses_parent", "recursive": false, "source": "session.index",
+  "authoritative": false, "indexSize": 1, "count": 1,
+  "limitations": [ … ],
+  "sessions": [ { "sessionID": "ses_child", "parentID": "ses_parent", "agent": "explore",
+                  "model": "deepseek/deepseek-flash", "variant": "default", "title": "…",
+                  "cost": 0.0005, "tokens": { "input": 3491, "output": 2 },
+                  "created": "2026-10-15T04:01:06.627Z", "updated": "…" } ] }
+```
+
+`source` говорит, какой маршрут дал ответ:
+
+- `session.list` — эта сборка предоставляет API листинга сессий; ответ
+  **авторитетный** и полный (`recursive` обходит поддерево постранично).
+- `session.index` — фолбэк, используемый OpenCode 2.0.28: у `ctx.session` есть
+  `get/create/…`, но **нет `list`**, поэтому детей нельзя перечислить из
+  хранилища. Плагин при setup подписывается на события `session.created` /
+  `session.deleted` и хранит `child → parent` в собственном хранилище плагина;
+  детали по каждому ребёнку читаются из `ctx.session.get()` в момент вызова.
+  Ответ **не авторитетный**; оговорки возвращаются в `limitations` (сессии,
+  созданные до старта инстанса плагина, не видны; пропуск событий скрывает
+  детей, созданных пока плагин был выгружен).
+- `E_NO_API` — нет ни одного маршрута. Фолбэк через сканирование контекста
+  (поиск частей инструмента `subagent` в `ctx.session.context`) был оценён и
+  отклонён: у летящих детей нет id сессии в их tool-части, а компакция стирает
+  историю. Открытый вопрос: листинг сессий со стороны плагина (или фильтр по
+  `parentID` в `ctx.session.context`) убрал бы фолбэк целиком.
+
+`E_INPUT` при некорректных аргументах, `E_NOT_FOUND`, когда родительской сессии
+нет, `E_ABORTED`, когда сессия остановлена.
+
+### `orch_uni_session_stats`
+
+```jsonc
+{}                                  // счётчики вызывающей сессии
+{ "sessionID": "ses_…" }            // любая сессия на этом сервере, не только дочерняя
+```
+
+```jsonc
+{ "ok": true, "sessionID": "ses_…",
+  "counters": {
+    "requests": 12, "promptTokensLast": 151204, "promptTokensMax": 161002,
+    "promptTokensMedian": 148900, "band": 1, "compactions": 1,
+    "compactionAttempts": 1, "compactionFailures": 0, "compactionSource": "event",
+    "reminders": 2, "toolCalls": 31, "outputsCapped": 1,
+    "outputCharsSaved": 18422, "errors": 0,
+    "toolCallsByTool": { "shell": 18, "bash": 6, "webfetch": 2, "read": 5 },
+    "toolOutputsCappedByTool": { "shell": 1, "bash": 0, "webfetch": 0, "read": 0 }
+  },
+  "limits": { "promptTokensSoft": 150000, "maxCompactions": 1, "maxToolOutputChars": 20000 },
+  "overBudget": true, "compactionLimitReached": true, "toolsPerTurn": 2.58,
+  "tracked": true,
+  "guard": { "available": true, "hooksRegistered": true, "sessionEnabled": true,
+             "toolOutputEnabled": true,
+             "toolOutputTools": ["shell", "bash", "webfetch"],
+             "compactionSource": "event", "eventLive": true,
+             "streamFailures": 0, "unkeyedCalls": 0 } }
+```
+
+`sessionID` может называть **любую сессию на этом сервере**, не только дочернюю
+вызывающего; это осознанно — по отчёту оркестратор контролирует все свои срезы.
+Счётчики принадлежат инстансу плагина, а `tracked` равен `true`, как только сессию
+наблюдало любое событие или хук; событие `session.deleted` её забывает. `band` —
+максимум достигнутого уровня бюджета (`0` ниже мягкого порога);
+`promptTokensMedian` — медиана по окну последних 256 запросов; `toolCalls` и
+per-tool счётчики включают вложенные вызовы Code Mode; `toolCallsByTool` и
+`toolOutputsCappedByTool` разносят вызовы и урезанные выводы по нормализованному
+имени инструмента (namespace снят, регистр нижний); `outputCharsSaved` — число
+символов, не байтов, и верхняя оценка (внедрённая заглушка вычитается).
+`compactions` считает только подтверждённые `session.compaction.ended`;
+`compactionAttempts` — каждый вызов хука `session.compaction`, поэтому на хосте с
+умершим или отсутствующим потоком событий попытки растут, а `compactions` и
+`compactionLimitReached` стоят (неудачная попытка не становится стоп-сигналом).
+Умерший поток событий один раз виден в `guard.streamFailures`; per-session
+`errors` считает только ошибки хуков, поэтому транспортная авария не
+приписывается каждой сессии. Дубликаты событий компакции считаются один раз
+только при наличии `event.id` или durable-позиции; без identity повторная
+доставка может пересчитать событие (fail-open в сторону счёта).
+Сессия, которую не отдаёт хранилище и не наблюдал этот инстанс, — `E_NOT_FOUND`
+(распознаётся по типизированным `_tag`/`name`/`code` — `Session.NotFoundError`,
+`SessionNotFoundError`, `NotFoundError`, `ENOENT` — с узким fallback по сообщению);
+`session.get`, вернувший `undefined` для ненаблюдаемой сессии, — тот же ответ
+«не найдено»; transient-ошибка `session.get` (блокировка, права, `unknown
+database`) — `E_INTERNAL`; известная сессия без запросов — валидный отчёт с
+`tracked: false`. Без `session.get` ненаблюдаемая сессия —
+`E_NO_API`, наблюдаемая — `ok` с `session: null` и записью в `limitations`.
+Коды: `E_INPUT`, `E_NOT_FOUND`, `E_INTERNAL`, `E_NO_API`, `E_UNAVAILABLE`
+(guard не зарегистрирован или его хуки не установились), `E_ABORTED`.
+
+## Гигиена сессии
+
+Плагин реализует протокол [`session-discipline.md`](./session-discipline.md):
+сессия = один срез, бюджет промпта ≤150k токенов, ≤1 компакция, вывод инструментов
+— в файл, в конце среза — handoff.
+
+Runtime-часть — три хука (`session.context`, `session.compaction`,
+`tool.execute.after`) и подписка на события компакции:
+
+- `session.context` — оценивает промпт (system + messages) и при переходе на
+  новый уровень бюджета добавляет одно короткое напоминание. Напоминание
+  инжектится **один раз при переходе уровня**, а не в каждом запросе; внутри
+  уровня текст стабилен, поэтому префикс-кэш не рвётся.
+- события компакции — хук `session.compaction` регистрируется **всегда**: он
+  считает попытки (`compactionAttempts`) и отдаёт tentative-напоминание ближайшему
+  запросу; напоминание не называет номер компакции и не заявляет лимит.
+  Подтверждает компакцию только `session.compaction.ended` (дедуп по `event.id`
+  или durable-позиции) и выставляет confirmed-note с номером и лимитом;
+  `session.compaction.failed` увеличивает `compactionFailures`, снимает
+  tentative-note и сохраняет confirmed-note, ещё ждущий доставки. Если поток
+  событий завершился или упал, `guard.eventLive` становится `false`,
+  `guard.compactionSource` — `"hook"`, а `guard.streamFailures` — `1`
+  (per-session `errors` остаётся `0`); хук продолжает считать попытки, но
+  подтверждённых компакций и ложного «лимит исчерпан» на этом пути нет.
+- `tool.execute.after` — для `shell`, `bash`, `webfetch` урезает вывод больше
+  `maxChars`: полный текст пишется в приватный корень на инстанс плагина
+  `os.tmpdir()/opencode-tool-output-<random>/` (POSIX: 0700 на корень и каталог
+  сессии, 0600 на файл), модель получает голову и путь. На Windows mode не
+  действует (замер: 0666), приватность там держится только на ACL каталога
+  `os.tmpdir()` и кодом не проверяется. Корень создаётся `mkdtemp` при setup,
+  поэтому заранее созданный каталог или
+  junction `opencode-tool-output` не используется; на POSIX корень обязан
+  принадлежать текущему uid и не давать доступа group/other, иначе guard
+  отключается с warning (fail-open: результат не трогается). Каталог сессии
+  (`s-<uuid>`) и файл (`c-<uuid>.txt`, запись `wx`) — случайные, их `realpath`
+  проверяется внутри корня. При выгрузке плагина корень удаляется best effort.
+  Строка с lone surrogate нормализуется один раз (U+FFFD), поэтому файл, голова и
+  счётчики описывают одну и ту же строку. Остаточный риск принят: same-user
+  атакующий всё ещё может подменить каталог
+  сессии между `realpath` и `writeFile` (в Node нет `openat`). Если `TMPDIR`
+  указывает внутрь воркспейса, файлы попадут туда. `read`, `write`, `edit`,
+  `execute` и инструменты комплекта не урезаются; kit-имя без namespace
+  (`session_stats`) отбрасывается в конфиге с warning.
+
+`maxCompactions: 0` отключает лимит компакций. `guard.toolOutputEnabled` равен
+`true` только когда приватный корень создан **и** эффективный список инструментов
+непуст; `guard.toolOutputTools` — этот список, `guard.unkeyedCalls` — вызовы
+хуков без непустого `sessionID` (отбрасываются, а не сливаются в бакет `""`).
+Пустой `tools` выключает кап с warning. Guard fail-open: ошибка хука не
+ломает запрос и не портит результат. Отключается флагами `enabled`:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": {
+        "sessionGuard": { "enabled": true, "promptTokensSoft": 150000, "maxCompactions": 1 },
+        "toolOutputGuard": {
+          "enabled": true,
+          "maxChars": 20000,
+          "headChars": 4000,
+          "tools": ["shell", "bash", "webfetch"]
+        }
+      }
+    }
+  ]
+}
+```
+
+Метрики среза — `orch_uni_session_stats`; закрытие среза — команда `/handoff`.
+
+## Модели
+
+Определения агентов не несут `model`; модели настраиваются у записи плагина в
+`opencode.json(c)`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": {
+        // Модель по умолчанию для всех агентов комплекта.
+        "model": "deepseek/deepseek-flash",
+        // Переопределения по агентам (id -> строка или развёрнутая форма).
+        "agents": {
+          "meta": "deepseek/deepseek-reasoner",
+          "fix-runner": { "providerID": "anthropic", "model": "claude-sonnet-4-5", "variant": "high" }
+        }
+      }
+    }
+  ]
+}
+```
+
+- `model` — модель по умолчанию для всех агентов комплекта; `agents.<id>` —
+  переопределение по агенту. Оба принимают `"provider/model[#variant]"` или
+  `{ providerID, model, variant }`.
+- Без опций агенты комплекта остаются без модели — субагенты наследуют модель
+  сессии.
+- Неверные значения игнорируются с предупреждением (`[orchestrator.uni] …`).
+- Субагенты работают на своей настроенной модели; основной `orchestrator` — на
+  модели сессии, поэтому модель, заданная для `orchestrator`, — информационная
+  для клиентов (на момент OpenCode 2.0.28).
+- Запись `agents` в конфиге или локальный Markdown-файл агента со своей моделью
+  всё равно побеждает — конфигурация применяется после пакетных плагинов.
+
+## Локаль
+
+Определения агентов и процессные документы поставляются per-locale — в
+`agents/<locale>/` и `docs/<locale>/`; сейчас это `ru` и `en` (английский
+контент — перевод русских оригиналов). Комплект выбирает локаль в таком порядке:
+
+1. `options.locale` (`"ru"` или `"en"`; полные теги вроде `"ru-RU"` принимаются);
+2. автодетект: `LC_ALL` / `LC_MESSAGES` / `LANG`, затем Intl-локаль рантайма
+   (настройка ОС);
+3. дефолт: `en`.
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": { "locale": "ru", "model": "deepseek/deepseek-flash" }
+    }
+  ]
+}
+```
+
+Если для запрошенной локали контент не поставлен, происходит откат к дефолтной
+локали с предупреждением в логе плагина. Обе локали регистрируют одних и тех же
+агентов под одними и теми же id — переключение локали меняет только язык
+промптов, процессных документов и описания reference.
+
+## Приоритет
+
+**Определения** агентов заполняются только для id, не определённых где-либо ещё:
+агент с тем же id из вашей конфигурации — запись `agents` в конфиге или
+Markdown-файл в `~/.config/opencode/agents/` (либо `.opencode/agents/`) —
+побеждает, и плагин пропускает своё определение. **Настроенная модель** (см.
+[Модели](#модели)) всё равно применяется к агентам комплекта; модель,
+определённая вашей записью агента или файлом, побеждает её, потому что
+конфигурация применяется после пакетных плагинов. То же правило «занято —
+пропускаем» действует для reference `audit-kit`.
+
+Если вы раньше устанавливали комплект копированием файлов агентов в свой
+конфиг-каталог, **удалите эти копии** после включения плагина, иначе устаревшие
+копии продолжат перекрывать определения, поставляемые плагином.
+
+## Заметки
+
+- Одна рантайм-зависимость: [`gray-matter`](https://www.npmjs.com/package/gray-matter)
+  для парсинга фронтматтера. OpenCode сам устанавливает зависимости пакетных
+  плагинов.
+- Id плагина: `orchestrator.uni`.
+- Пакет загружается напрямую из TypeScript: `exports` указывает на `index.ts`.
+  Шага сборки и каталога `dist/` нет (тот же приём, что в `@opencode/plugin-figma`).
+- Поставляются только файлы из `package.json#files`: `index.ts`, `lib/`, `schemas/`,
+  `agents/`, `docs/`, `README.md`, `README.ru.md`, `LICENSE`.
+
+<p align="right">(<a href="../../README.ru.md">назад в README</a>)</p>

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-orchestrator-uni",
-  "version": "0.5.1",
-  "description": "Native OpenCode V2 plugin that registers the orchestrator agent kit (root orchestrator, audit subagents, fix-runner) and exposes the kit's process documents as the audit-kit reference.",
+  "version": "0.5.2",
+  "description": "An OpenCode V2 plugin that runs coding work as an evidence-driven audit loop: a root orchestrator, read-only auditors, one fix-runner, and deterministic verification tools.",
   "type": "module",
   "license": "MIT",
   "author": "OniVe",