opencode-orchestrator-uni 0.4.0 → 0.5.1

package/docs/ru/root-runbook.md

@@ -5,6 +5,8 @@
 - **Root (главный агент)** — не аудирует: формирует бриф, запускает субагентов, сводит отчёты; по «недоказуемым» — решение владельца: root оформляет вопрос, фиксирует риск и эскалирует. Ведёт реестр принятых рисков, вносит правки отдельными коммитами, решает «ship».
 - **Субагенты** (read-only): `factcheck`, `empiric`, `invariant`, `arbiter`, (на воротах) `redteam`, `meta`.
 
+Сессионная гигиена среза — границы, бюджет контекста (≤150k токенов, ≤1 компакция) и handoff — в `session-discipline.md`.
+
 ## Шаблон брифа `case-<id>.md` (общий для всех шагов)
 
 ```
@@ -26,7 +28,7 @@
 3. **Свод root'ом**: распарсить JSON-блоки; вычислить вердикты (ready/not_ready), открытые MAJOR, пересечения и расхождения (по location+механизму). Материализовать свод-артефакт `reports/summary-<id>.md` (определение — `call-mechanics.md` §4): по каждой MAJOR — {id, verifier_role, verdict, evidence}; refuted-список (явный, даже пустой); принятые риски; ревизия состояния (хэш каталога/коммит).
 4. **Верификация MAJOR (перекрёстная, fail-closed)**: каждая MAJOR-находка подтверждается независимо **сессией противоположной роли** (не автором находки) — `subagent(agent="<sibling>", sessionID=<сессия противоположной роли>, prompt="Находка <id> контрагента: <текст>. Evidence автора: <команда→вывод>. Ревизия состояния: <хэш каталога/коммит>. Подтверди или опровергни своим воспроизведением; дефолт — не подтверждена. Верни: {id, verifier_role, verdict: confirmed|refuted|partial|unavailable, evidence}.")`. `verifier_role` ≠ роль автора; `partial`/`unavailable` = «не подтверждена»; `refuted` — в список refuted для сводки; сбой/таймаут верификатора — «не подтверждена» + шум. Не подтверждена → в правки не идёт (спор → шаг 5, арбитр); статусы верификации пишутся в свод `reports/summary-<id>.md` (шаг 3). Если MAJOR-находка независимо воспроизведена обеими ролями в их собственных прогонах — взаимное подтверждение засчитывается как верификация (обе стороны в свод), отдельный прогон не требуется. sessionID при вызове обязателен: без него это новая сессия, а не продолжение — дефект шага.
 5. **Арбитр — только при расхождениях**: `subagent(agent="arbiter", prompt="Спорные пункты: <пункт → evidence A → evidence B>. По каждому: подтверждён/опровергнут/недоказуем + команда/цитата.")`. Вердикт свода (и верификация/арбитраж) фиксируются ДО правок и **вместе с ревизией состояния** (хэш каталога/коммит); любая правка после фиксации вердикта → повторный прогон (re-audit) либо явное понижение вердикта: до вердикта — не править.
-6. **Правки** по порогу: микро — root сам; средние/крупные — `fix-runner` (вход: список «к закрытию» — id, локация, механизм, **класс/область** (пути + правило поиска однотипных мест), repro-до, критерий-после, severity — плюс границы и **бюджет/лимит (время, число правок)**; выход: fix-runner/v1 с before/after/`proof`/тестами). Отдельные коммиты `fix-<round>`; обновить реестр: `closed` / `accepted-risk` (с причиной). Root проверяет дельту раунда — `git diff <round-base>..HEAD --stat` (не только `git show --stat`) — до re-audit. Стенд раунда (если в комплекте поставляется проверочный стенд — инструмент `tools/kit-verify` каталога комплекта; в раундах по другим проектам — только если стенд явно включён в границы вызова): baseline стенда в промпт фиксера (если вывод передан — фиксер не дублирует прогон); закрытие — повторный прогон стенда; оба вывода — в поле `stand` отчёта. Стенд поставляется в git-чекауте комплекта: в npm-пакете каталог `tools/` не поставляется → `stand: unavailable` и собственные воспроизводимые проверки. Статусы `fix-runner`: `needs_decision` → решение root (при споре — арбитр; если решение за владельцем — эскалация) с фиксацией в реестре рисков; `not_closed` → повторная итерация с тем же id; `budget_exceeded` → расширить бюджет решением владельца либо разбить список и продолжить с того же id (коммиты и worktree сохранить до закрытия или уборки); поле `out_of_scope` (замечено вне списка) → включить в следующий список «к закрытию» или эскалировать. Статус **`no_report`** (отчёта нет: фиксер упал/таймаут) — root фиксирует в своде выполненную работу (worktree, ветка, base SHA) и `no_report`; ветку/коммиты НЕ сливать; приоритет — resume в том же worktree; иначе убрать: `git worktree remove --force` и решить судьбу ветки. Частичный коммит без отчёта в основную ветку не вливается. Несколько `fix-runner` — только в отдельных worktree **вне дерева проекта** (у каждого своя ветка `fix/<round>-<n>`); путь пространства сверяется префиксами путей (`git -C <project> rev-parse --show-toplevel` не должен быть префиксом канонического пути пространства; иначе — `needs_decision`, пространство не создаётся и не используется); перед запуском root считает пересечение **наборов файлов** (пути + правило поиска класса), а не только списков: пересечение ⇒ сериализация или разнесение путей. Посадка сессии в её пространство: `session_move({sessionID, directory})` (если доступен), иначе `cd <абс. путь>` + абсолютные пути; ни то ни другое — параллельный запуск запрещён. В свежем worktree зависимости ставятся до прогонов (`npm ci` / `bun install`). После завершения root сводит результаты строго по **полному hex SHA** из отчёта: `commit` принимается только как `^[0-9a-f]{40}$` — проверка ДО любых git-команд (имена веток из отчётов для сведения не использовать; `check-ref-format` и `rev-parse --verify` барьером не являются — резолвят имена); SHA — отдельным аргументом в кавычках; семантические проверки: `git cat-file -t <sha>` = `commit`, `git merge-base --is-ancestor <base> <sha>`, `git diff --quiet <base> <sha>` ложно (дельта непуста), `<sha> != <base>`; `Already up to date` (пустая дельта) ⇒ `not_consolidated`, не `closed`; merge/cherry-pick по SHA, прогоняет проверки на сведённом состоянии и только тогда фиксирует `closed`; worktree не удалять до подтверждённого переноса коммита, после — `git worktree remove --force` и осознанное решение по ветке; повторный запуск после инцидента — resume в том же worktree либо явное удаление/переименование ветки решением root'а (повторный `git worktree add -b` падает при занятой ветке), `locked` worktree — `git worktree unlock` либо `git worktree remove -f -f`.
+6. **Правки**: только `fix-runner` — root код, доки и тесты не правит; его запись ограничена артефактами аудита/состояния (вход: список «к закрытию» — id, локация, механизм, **класс/область** (пути + правило поиска однотипных мест), repro-до, критерий-после, severity — плюс границы и **бюджет/лимит (время, число правок)**; выход: fix-runner/v1 с before/after/`proof`/тестами). Отдельные коммиты `fix-<round>`; обновить реестр: `closed` / `accepted-risk` (с причиной). Root проверяет дельту раунда — `git diff <round-base>..HEAD --stat` (не только `git show --stat`) — до re-audit. Стенд раунда (если в комплекте поставляется проверочный стенд — инструмент `tools/kit-verify` каталога комплекта; в раундах по другим проектам — только если стенд явно включён в границы вызова): baseline стенда в промпт фиксера (если вывод передан — фиксер не дублирует прогон); закрытие — повторный прогон стенда; оба вывода — в поле `stand` отчёта. Стенд поставляется в git-чекауте комплекта: в npm-пакете каталог `tools/` не поставляется → `stand: unavailable` и собственные воспроизводимые проверки. Статусы `fix-runner`: `needs_decision` → решение root (при споре — арбитр; если решение за владельцем — эскалация) с фиксацией в реестре рисков; `not_closed` → повторная итерация с тем же id; `budget_exceeded` → расширить бюджет решением владельца либо разбить список и продолжить с того же id (коммиты и worktree сохранить до закрытия или уборки); поле `out_of_scope` (замечено вне списка) → включить в следующий список «к закрытию» или эскалировать. Статус **`no_report`** (отчёта нет: фиксер упал/таймаут) — root фиксирует в своде выполненную работу (worktree, ветка, base SHA) и `no_report`; ветку/коммиты НЕ сливать; приоритет — resume в том же worktree; иначе убрать: `git worktree remove --force` и решить судьбу ветки. Частичный коммит без отчёта в основную ветку не вливается. Несколько `fix-runner` — только в отдельных worktree **вне дерева проекта** (у каждого своя ветка `fix/<round>-<n>`); путь пространства сверяется префиксами путей (`git -C <project> rev-parse --show-toplevel` не должен быть префиксом канонического пути пространства; иначе — `needs_decision`, пространство не создаётся и не используется); перед запуском root считает пересечение **наборов файлов** (пути + правило поиска класса), а не только списков: пересечение ⇒ сериализация или разнесение путей. Посадка сессии в её пространство: `session_move({sessionID, directory})` (если доступен), иначе `cd <абс. путь>` + абсолютные пути; ни то ни другое — параллельный запуск запрещён. В свежем worktree зависимости ставятся до прогонов (`npm ci` / `bun install`). После завершения root сводит результаты строго по **полному hex SHA** из отчёта: `commit` принимается только как `^[0-9a-f]{40}$` — проверка ДО любых git-команд (имена веток из отчётов для сведения не использовать; `check-ref-format` и `rev-parse --verify` барьером не являются — резолвят имена); SHA — отдельным аргументом в кавычках; семантические проверки: `git cat-file -t <sha>` = `commit`, `git merge-base --is-ancestor <base> <sha>`, `git diff --quiet <base> <sha>` ложно (дельта непуста), `<sha> != <base>`; `Already up to date` (пустая дельта) ⇒ `not_consolidated`, не `closed`; merge/cherry-pick по SHA, прогоняет проверки на сведённом состоянии и только тогда фиксирует `closed`; worktree не удалять до подтверждённого переноса коммита, после — `git worktree remove --force` и осознанное решение по ветке; повторный запуск после инцидента — resume в том же worktree либо явное удаление/переименование ветки решением root'а (повторный `git worktree add -b` падает при занятой ветке), `locked` worktree — `git worktree unlock` либо `git worktree remove -f -f`.
 7. **Re-audit = resume те же сессии** (sessionID из шага 2): «Правки: <диапазон + фактический список изменённых файлов>. Проверь закрытие своих находок и отсутствие регрессий; верни обновлённый SGR.» — исторически так и делалось (продолжение сессий GLM/DS). sessionID обязателен: вызов без него (новая сессия вместо продолжения) — дефект шага. Re-audit и `closed` — на **сведённом** состоянии: доказательство приёмки (after/stand) перепривязывается к сведённому commit SHA; `closed` без отчёта фиксера (`no_report`) запрещён; нет ключа `commit` или `workspace` в отчёте фиксера ⇒ `not_closed`.
 8. **Повторяй шаги 3–7, пока не достигнут полный ready** (число кругов не ограничено; все роли ready, MAJOR=0). С 3-го круга нерешённые пункты — арбитр поштучно; повторяющиеся ложные — снять и записать как шум аудита.
 9. **Ворота (релиз; порядок: ред-тим → мета)**: замороженный коммит → `redteam` (мандат фальсификации + корпуса/стенды) → цикл по его находкам (MAJOR — с верификацией сессией противоположной роли) → `meta` (на вход: отчёты + свод `reports/summary-<id>.md`; evidence, полнота, отсутствие «зелёные тесты = проверено»).

package/docs/ru/session-discipline.md

@@ -0,0 +1,225 @@
+# Гигиена сессии: как вести разработку
+
+Документ задаёт протокол работы сессии: где её границы, какой бюджет контекста,
+когда делегировать, как обращаться с выводом инструментов и что остаётся после
+сессии. Он дополняет `context-efficiency.md` (бюджет файлов инструкций) и
+`root-runbook.md` (аудиторский цикл): там — про артефакты и вердикты, здесь —
+про то, как не сжечь контекст и не потерять решения по дороге.
+
+## Зачем это нужно
+
+- Контекст — расходуемый ресурс, а не память проекта. С ростом входа качество
+  падает даже на простых задачах (context rot); «влезло в окно» не значит
+  «модель это использует».
+- Компакция — lossy-пересказ. После неё агент помнит не решения, а их краткое
+  изложение; повторная компакция пересказывает пересказ.
+- Замер длинной сессии: 13 253 хода, 19 компакций, медиана промпта выросла с
+  314k до 780k токенов. Почти всё это — повторная пересылка истории, а не работа.
+  Это внутренний замер проекта-потребителя: артефакт в репозиторий не приложен,
+  из этого репозитория цифры не воспроизводятся.
+
+Цель протокола — держать рабочее состояние маленьким, а решения — в файлах,
+которые переживают сессию.
+
+## 1. Сессия = срез
+
+Сессия — это один срез с измеримым DoD, а не весь проект.
+
+| Правило | Значение |
+| --- | --- |
+| Бюджет оценки промпта | ≤ 150k токенов |
+| Компакций на срез | ≤ 1 |
+| Стоп-сигнал | первая компакция |
+| Обязательный выход | handoff + коммит |
+
+- При первом признаке приближения к бюджету — не «дожимать», а закрывать срез:
+  handoff, коммит, новая сессия.
+- После первой компакции срез закрывается в любом случае: суммаризация уже
+  потеряла детали, и дальнейшая работа идёт по пересказу.
+- Резать работу по волнам, гейтам или пакетам правок; смена фазы (план →
+  реализация → приёмка) — всегда новая сессия.
+
+## 2. Разделение ролей
+
+- Разведка и проверка («найти», «понять», «воспроизвести») — субагентам: у них
+  чистый контекст, а в ответ возвращается 1–2k токенов выводов, а не дамп.
+- Реализация — одному пишущему субагенту на рабочее пространство (root сам код, доки и тесты не правит — только артефакты аудита/состояния): связанные решения должны
+  приниматься в одном контексте (иначе параллельные агенты расходятся в стиле и
+  контрактах).
+- Решения, сведение и приёмка — root-оркестратору.
+- Аудиторский цикл не меняется: re-audit — resume тех же сессий; короткие
+  аудиторские сессии бюджету не угрожают.
+
+Практическое правило: делегируй **исследование** широко, **реализацию** — узко,
+**интеграцию** держи централизованной.
+
+## 3. Батчинг инструментов
+
+Каждый ход — это полная пересылка промпта. Один инструмент за ход умножает
+бюджет на число мелочей.
+
+- ≥ 3 независимые команды за ход или один скрипт вместо пяти-десяти вызовов.
+- Длинные команды WSL выноси в скрипт-обёртку: строка на 250 символов в каждом
+  ходе дороже, чем файл, который читается один раз.
+- Для чтения файлов — `read` с `limit`/`offset`, а не `cat` целиком.
+- Цель по метрике: ≥ 2 инструментов на ход.
+
+## 4. Вывод инструментов
+
+- Всё, что больше 20k символов, — в файл; в контекст идёт голова (4k) и путь.
+  Это делает guard автоматически для `shell`, `bash`, `webfetch`.
+- Скриншоты и бинарные вложения — файлом и путём, не base64 в контексте.
+- `execute` (Code Mode) guard не режет: ограничивай результат в самом скрипте —
+  возвращай сводку и путь, а не сырой JSON на сотни килобайт.
+- `read`, `write`, `edit` и инструменты комплекта не урезаются: у них свой
+  контракт, и потеря содержимого ломает работу.
+
+## 5. Состояние в файлах
+
+- `handoff` — обязательный выход среза (шаблон ниже); путь по умолчанию —
+  `docs/planning/handoff-<YYYY-MM-DD>.md`, если каталога нет — корень проекта.
+- `decisions` — решения и причины; одно решение — одна запись; путь по умолчанию —
+  `docs/planning/decisions-<YYYY-MM-DD>.md`.
+- `state` — ветка, гейты, открытые риски, следующие три шага; обновляется перед
+  новой сессией; путь по умолчанию — `docs/planning/state.md`.
+- Новая сессия начинается с `state` и целевого раздела SPEC, а не с пересказа
+  прошлой сессии.
+
+## 6. Модели
+
+- По умолчанию — дешёвая модель; дорогая — только на архитектурные решения,
+  ревью и разбор спорного.
+- Правки документов, чтение и механические проверки не требуют дорогой модели.
+- Замер: 223 хода дорогой модели — $63, 104 хода дешёвой — $0.09. Один
+  переключатель модели экономит больше, чем любая оптимизация промпта. Это
+  внутренний замер проекта-потребителя: артефакт в репозиторий не приложен, из
+  этого репозитория цифры не воспроизводятся.
+
+## 7. Метрики
+
+| Метрика | Цель | Где смотреть |
+| --- | --- | --- |
+| Оценка промпта (медиана) | ≤ 150k | `orch_uni_session_stats` |
+| Компакций на срез | ≤ 1 | `orch_uni_session_stats` |
+| Инструментов на ход (`toolCalls/requests`, он же `toolsPerTurn`) | ≥ 2 | `orch_uni_session_stats` |
+| Доля урезанных выводов среди вызовов инструмента (`toolOutputsCappedByTool.shell / toolCallsByTool.shell`; так же `bash`, `webfetch`) | < 5% | `orch_uni_session_stats` |
+| Handoff в конце среза | есть | рабочее дерево |
+
+`orch_uni_session_stats` отдаёт счётчики текущего инстанса плагина и настроенные
+лимиты; исторические прогоны считаются по базе сессий на стороне проекта.
+
+## 8. Guard
+
+Guard — это хуки плагина и подписка на события компакции, а не запреты:
+
+- `session.context` — оценивает промпт и добавляет одно короткое напоминание при
+  переходе на новый уровень бюджета. Напоминание инжектится один раз при
+  переходе уровня, а не в каждом запросе; внутри уровня текст стабилен, поэтому
+  префикс-кэш не рвётся.
+- события компакции — хук `session.compaction` регистрируется всегда: он считает
+  попытки (`compactionAttempts`) и отдаёт tentative-напоминание ближайшему
+  запросу при задержке терминального события; напоминание не называет номер
+  компакции и не заявляет лимит. Подтверждает компакцию только
+  `session.compaction.ended` (дедуп по `event.id` или durable-позиции); он же
+  двигает `compactions` и лимит. `session.compaction.failed` увеличивает
+  `compactionFailures`, снимает tentative-note и сохраняет confirmed-note, ещё
+  ждущий доставки. Если поток событий завершился или упал, guard выставляет
+  `eventLive: false`, `compactionSource: "hook"` и `streamFailures: 1`
+  (per-session `errors` остаётся `0`), хук уже зарегистрирован и попытки
+  продолжают считаться; подтверждённых компакций и стопа на этом пути нет —
+  ложного «лимит исчерпан» не бывает. Источник, liveness и сбои потока видны в
+  `guard`.
+- `tool.execute.after` — урезает вывод настроенных инструментов и складывает
+  полный текст в приватный корень на инстанс плагина
+  `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` указывает внутрь воркспейса, файлы попадут туда.
+
+Конфигурация (значения по умолчанию):
+
+```jsonc
+{
+  "sessionGuard": {
+    "enabled": true,
+    "promptTokensSoft": 150000,
+    "maxCompactions": 1
+  },
+  "toolOutputGuard": {
+    "enabled": true,
+    "maxChars": 20000,
+    "headChars": 4000,
+    "tools": ["shell", "bash", "webfetch"]
+  }
+}
+```
+
+`maxCompactions: 0` отключает лимит компакций. `guard.toolOutputEnabled` равен
+`true` только когда приватный корень создан **и** эффективный список инструментов
+непуст; `guard.toolOutputTools` — этот список (после нормализации и отбрасывания
+защищённых и kit-имён), `guard.unkeyedCalls` — число вызовов хуков без непустого
+`sessionID` (такой ввод отбрасывается, а не сливается в бакет `""`). Пустой
+`tools` — явный или после отбрасывания всех имён — выключает кап с warning.
+Принятые ограничения: каталог сессии `s-<uuid>` живёт до выгрузки плагина — он не
+удаляется ни при `session.deleted`, ни после отброшенного капа (например, при
+неизменяемом результате), а освобождается вместе с корнем; нормализация lone
+surrogate опирается на ES2024 `String.prototype.isWellFormed`/`toWellFormed`
+(минимальная версия рантайма в `engines` не зафиксирована — на старом рантайме кап
+деградирует fail-open: `errors` +1, результат не тронут).
+В счётчиках `toolCalls` и
+per-tool счётчики включают вложенные вызовы Code Mode, а `outputCharsSaved` —
+верхняя оценка в символах (внедрённая заглушка вычитается). `toolCallsByTool` и
+`toolOutputsCappedByTool` разносят вызовы и урезанные выводы по нормализованному
+имени инструмента (namespace снят, регистр нижний). Дубликаты событий компакции
+считаются один раз только при наличии `event.id` или durable-позиции; без
+identity повторная доставка может пересчитать событие (fail-open в сторону
+счёта).
+
+Guard fail-open: ошибка хука не ломает запрос и не портит результат инструмента.
+Он не пишет в рабочее дерево (кроме случая `TMPDIR` внутри воркспейса — см.
+выше) и не блокирует действия — только напоминает и урезает вывод. Отключить
+можно любым из флагов `enabled`.
+
+## Шаблон handoff
+
+```md
+# Handoff: <срез> — <YYYY-MM-DD>
+
+<!-- Файл: docs/planning/handoff-<YYYY-MM-DD>.md; нет каталога — корень проекта. -->
+
+## Цель и DoD
+Одно предложение цели и проверяемый критерий готовности.
+
+## Сделано
+- Что изменено; чем подтверждено (команда, тест, коммит).
+
+## Не сделано
+- Что осталось и почему (блокер, решение владельца, следующая волна).
+
+## Решения
+- Решение — причина; ссылка на документ или коммит.
+
+## Риски и ограничения
+- Принятый риск — кем и до какого момента.
+
+## Следующий шаг
+Одно конкретное действие для следующей сессии.
+```
+
+## Чек-лист среза
+
+- [ ] Срез закрыт по DoD, а не по «кончилось время».
+- [ ] Handoff записан и ссылается на доказательства.
+- [ ] Решения и риски зафиксированы в файлах, а не только в переписке.
+- [ ] Рабочее дерево чистое или явно описано в handoff.
+- [ ] Следующая сессия начинается с `state` и SPEC, а не с пересказа.

package/index.ts

@@ -24,7 +24,7 @@
  * - The `audit-kit` reference is registered only if that name is free; it points
  *   at this package's `docs/` directory so sessions can read the process
  *   documents directly.
- * - Slash commands (`/agents-md`, `/spec`) are registered through
+ * - Slash commands (`/agents-md`, `/spec`, `/handoff`) are registered through
  *   `ctx.command.transform`; their handlers inject a workflow prompt into the
  *   current session and never write files themselves.
  *
@@ -53,7 +53,9 @@ import { fileURLToPath } from "node:url"
 import type { Agent, Model, Plugin, Reference } from "@opencode/plugin"
 import matter from "gray-matter"
 import { registerKitCommands } from "./lib/commands"
+import { createSessionBudget, readSessionBudgetOptions, safeJson } from "./lib/session-budget"
 import { registerAuditTools } from "./lib/tools"
+import { createWriteGuard } from "./lib/write-guard"
 
 /** Stable plugin id: diagnostics, enable/disable selectors, storage scope. */
 export const PLUGIN_ID = "orchestrator.uni"
@@ -118,10 +120,12 @@ function localeCandidates(): string[] {
 const REFERENCE_DESCRIPTIONS: Record<Locale, string> = {
   ru:
     "Процессные документы комплекта оркестратора (аудиторский цикл): call-mechanics.md, " +
-    "process-ready-loop.md, root-runbook.md, instruction-other-session.md, context-efficiency.md.",
+    "process-ready-loop.md, root-runbook.md, instruction-other-session.md, context-efficiency.md, " +
+    "session-discipline.md.",
   en:
     "Process documents of the orchestrator agent kit (audit loop): call-mechanics.md, " +
-    "process-ready-loop.md, root-runbook.md, instruction-other-session.md, context-efficiency.md.",
+    "process-ready-loop.md, root-runbook.md, instruction-other-session.md, context-efficiency.md, " +
+    "session-discipline.md.",
 }
 
 /** Frontmatter keys this loader understands; anything else is reported and ignored. */
@@ -353,7 +357,7 @@ function readLocaleOptions(options: unknown): Locale | undefined {
   if (raw === undefined) return undefined
   const locale = parseLocaleTag(raw)
   if (!locale) {
-    warn(`options.locale: expected one of ${SUPPORTED_LOCALES.join("|")}, got ${JSON.stringify(raw)}, ignored`)
+    warn(`options.locale: expected one of ${SUPPORTED_LOCALES.join("|")}, got ${safeJson(raw)}, ignored`)
   }
   return locale
 }
@@ -408,25 +412,53 @@ async function setup(ctx: Plugin.Context): Promise<Plugin.Cleanup | undefined> {
   })
 
   // Deterministic, read-only audit tools: `orch_uni_validate_report`,
-  // `orch_uni_context_lint`, `orch_uni_snapshot`, `orch_uni_sessions` (see
-  // `lib/tools.ts` and README «Tools»). The tools cleanup only stops the
-  // background session-index subscription; the commands cleanup disposes the
-  // command transform registration. A failure after the tools are registered
-  // must abort that subscription too — otherwise a half-registered plugin leaks
-  // an event listener for the lifetime of the server.
-  const toolsCleanup = await registerAuditTools(ctx)
+  // `orch_uni_context_lint`, `orch_uni_snapshot`, `orch_uni_sessions`,
+  // `orch_uni_session_stats` (see `lib/tools.ts` and README «Tools»). The session
+  // budget registers the protocol hooks (context/compaction/tool output); the
+  // tools cleanup stops the background session-index subscription; the commands
+  // cleanup disposes the command transform registration. A failure after the
+  // tools are registered must abort that subscription too — otherwise a
+  // half-registered plugin leaks an event listener for the lifetime of the server.
+  const sessionBudget = await createSessionBudget(ctx, readSessionBudgetOptions(ctx.options, warn), locale, warn)
+  // The path-root write guard enforces the orchestrator's artifact-only edit
+  // contract beyond what flat `permissions` can express (see `lib/write-guard.ts`).
+  // It registers on the host's permission hook and stays a no-op on a host without
+  // that API — a missing hook is reported, never fatal. Registration happens
+  // before the tools so a later failure disposes the guard with the rest of the chain.
+  const writeGuard = await createWriteGuard(ctx, {
+    locationDirectory: String(ctx.location.directory),
+    warn,
+  })
+  let toolsCleanup: () => void
+  try {
+    toolsCleanup = await registerAuditTools(ctx, { sessionBudget })
+  } catch (error) {
+    await writeGuard.cleanup()
+    await sessionBudget.cleanup()
+    throw error
+  }
   let commandsCleanup: Plugin.Cleanup
   try {
     commandsCleanup = await registerKitCommands(ctx, locale)
   } catch (error) {
     toolsCleanup()
+    await writeGuard.cleanup()
+    await sessionBudget.cleanup()
     throw error
   }
   return async () => {
     try {
       await commandsCleanup()
     } finally {
-      toolsCleanup()
+      try {
+        toolsCleanup()
+      } finally {
+        try {
+          await writeGuard.cleanup()
+        } finally {
+          await sessionBudget.cleanup()
+        }
+      }
     }
   }
 }

package/lib/commands.ts

@@ -1,10 +1,10 @@
 /**
- * Slash commands of the kit: `/agents-md` and `/spec`.
+ * Slash commands of the kit: `/agents-md`, `/spec` and `/handoff`.
  *
  * Commands are prompts, not writers: `execute` injects a short workflow prompt
  * into the current session, and the orchestrator runs it with the usual
  * evidence/approval rules. The detailed templates and checklists live in
- * `docs/<locale>/context-efficiency.md`.
+ * `docs/<locale>/context-efficiency.md` and `docs/<locale>/session-discipline.md`.
  */
 import type { Plugin } from "@opencode/plugin"
 
@@ -12,17 +12,22 @@ type CommandLocale = "ru" | "en"
 
 /** Arguments typed after the slash command, without a duplicated command token. */
 function commandArgs(text: string): string {
-  return text.replace(/^\s*\/(?:agents-md|spec)\b/i, "").trim()
+  return text.replace(/^\s*\/(?:agents-md|spec|handoff)\b/i, "").trim()
 }
 
-const DESCRIPTIONS: Record<CommandLocale, { readonly agentsMd: string; readonly spec: string }> = {
+const DESCRIPTIONS: Record<
+  CommandLocale,
+  { readonly agentsMd: string; readonly spec: string; readonly handoff: string }
+> = {
   ru: {
     agentsMd: "Создать или проверить AGENTS.md по шаблону context-efficiency.md.",
     spec: "Создать или проверить SPEC.md по шаблону context-efficiency.md.",
+    handoff: "Сформировать handoff среза по шаблону session-discipline.md.",
   },
   en: {
     agentsMd: "Create or audit AGENTS.md using the context-efficiency.md template.",
     spec: "Create or audit SPEC.md using the context-efficiency.md template.",
+    handoff: "Write the slice handoff using the session-discipline.md template.",
   },
 }
 
@@ -84,14 +89,43 @@ function specPrompt(locale: CommandLocale, brief: string): string {
   ].join("\n")
 }
 
-/** Register `/agents-md` and `/spec`; the cleanup disposes the transform registration. */
+function handoffPrompt(locale: CommandLocale, goal: string): string {
+  if (locale === "ru") {
+    return [
+      "[Команда /handoff]",
+      `Срез: ${goal}.`,
+      "",
+      "Работай по документу session-discipline.md из reference audit-kit.",
+      "1. Собери факты только из текущей сессии и рабочего дерева: что сделано, чем подтверждено (команды, тесты, коммиты), что не сделано и почему.",
+      "2. Заполни шаблон handoff из session-discipline.md: цель и DoD, сделано, не сделано, решения и причины, риски/принятые ограничения, следующий шаг.",
+      "3. Запиши файл `docs/planning/handoff-<YYYY-MM-DD>.md` (нет каталога — корень проекта) инструментом `write`, не shell-heredoc.",
+      "4. Ничего не додумывай: неизвестное помечай «не проверено»; секреты и токены в handoff не переноси.",
+      "5. Покажи путь файла, краткий diff и открытые вопросы; канонические документы не меняй без подтверждения.",
+      "6. Если дерево грязное — предложи коммит по правилам проекта; не коммить без подтверждения владельца.",
+    ].join("\n")
+  }
+  return [
+    "[Command /handoff]",
+    `Slice: ${goal}.`,
+    "",
+    "Follow session-discipline.md from the audit-kit reference.",
+    "1. Collect facts from the current session and the working tree only: what is done, what proves it (commands, tests, commits), what is not done and why.",
+    "2. Fill the handoff template from session-discipline.md: goal and DoD, done, not done, decisions and reasons, risks/accepted limits, next step.",
+    "3. Write `docs/planning/handoff-<YYYY-MM-DD>.md` (use the project root when the directory is absent) with the `write` tool, not a shell heredoc.",
+    "4. Do not invent facts: mark the unknown as `unverified`; never copy secrets or tokens into the handoff.",
+    "5. Show the file path, a short diff and open questions; do not change canonical documents without approval.",
+    "6. If the working tree is dirty, propose a commit per the project rules; do not commit without the owner's approval.",
+  ].join("\n")
+}
+
+/** Register `/agents-md`, `/spec` and `/handoff`; the cleanup disposes the transform registration. */
 export async function registerKitCommands(ctx: Plugin.Context, locale: CommandLocale): Promise<Plugin.Cleanup> {
   // The command API is optional in a host build. A missing `list` was already
   // tolerated; a missing `transform` used to throw out of `setup` and take every
   // agent and tool with it, so it degrades to a warning plus a no-op cleanup.
   const command = (ctx as Partial<Plugin.Context>).command
   if (command === undefined || typeof command.transform !== "function") {
-    console.warn("orch-uni: this host has no command API; /agents-md and /spec are not registered")
+    console.warn("orch-uni: this host has no command API; /agents-md, /spec and /handoff are not registered")
     return async () => {}
   }
   let existing = new Set<string>()
@@ -141,6 +175,28 @@ export async function registerKitCommands(ctx: Plugin.Context, locale: CommandLo
         },
       })
     }
+    if (!existing.has("handoff")) {
+      editor.add({
+        name: "handoff",
+        description: DESCRIPTIONS[locale].handoff,
+        execute: async (input) => {
+          await ctx.session.prompt({
+            sessionID: input.sessionID,
+            text: handoffPrompt(
+              locale,
+              commandArgs(input.prompt.text) ||
+                (locale === "ru"
+                  ? "текущая сессия — опиши срез по фактам"
+                  : "the current session — describe the slice from facts"),
+            ),
+            ...(input.prompt.files === undefined ? {} : { files: input.prompt.files }),
+            ...(input.prompt.agents === undefined ? {} : { agents: input.prompt.agents }),
+            ...(input.prompt.skills === undefined ? {} : { skills: input.prompt.skills }),
+            delivery: input.delivery,
+          })
+        },
+      })
+    }
   })
   return async () => {
     await registration.dispose()