opencode-orchestrator-uni 0.4.0 → 0.5.0

package/docs/en/session-discipline.md

@@ -0,0 +1,230 @@
+# Session discipline: how to run development
+
+This document defines the session protocol: where a session starts and ends, its
+context budget, when to delegate, how to treat tool output, and what survives the
+session. It complements `context-efficiency.md` (the instruction-file budget) and
+`root-runbook.md` (the audit loop): those cover artifacts and verdicts, this one
+covers keeping context small and decisions pinned.
+
+## Why it matters
+
+- Context is a consumable resource, not the project's memory. As input grows,
+  quality degrades even on simple tasks (context rot); "it fits the window" does
+  not mean "the model uses it".
+- Compaction is a lossy summary. After it the agent remembers a paraphrase of
+  decisions, not the decisions; a second compaction paraphrases a paraphrase.
+- A measured long session: 13 253 turns, 19 compactions, the median prompt grew
+  from 314k to 780k tokens. Almost all of that is re-sending history, not work.
+  This is an internal measurement of a consumer project: the artifact is not
+  attached to the repository, and the figures are not reproducible from it.
+
+The protocol keeps the working state small and the decisions in files that
+outlive the session.
+
+## 1. A session is one slice
+
+A session is one slice with a measurable DoD, not the whole project.
+
+| Rule | Value |
+| --- | --- |
+| Estimated prompt budget | ≤ 150k tokens |
+| Compactions per slice | ≤ 1 |
+| Stop signal | the first compaction |
+| Required output | handoff + commit |
+
+- At the first sign of approaching the budget, close the slice instead of pushing
+  on: handoff, commit, new session.
+- After the first compaction the slice always closes: the summary has already lost
+  details and further work runs on a paraphrase.
+- Cut work by waves, gates or fix batches; a phase change (plan → implementation →
+  acceptance) always starts a new session.
+
+## 2. Role separation
+
+- Investigation and verification ("find", "understand", "reproduce") go to
+  subagents: they get a clean context and return 1–2k tokens of findings instead
+  of a dump.
+- Implementation goes to one writer per workspace: related decisions must be made
+  in one context (otherwise parallel agents diverge in style and contracts).
+- Decisions, consolidation and acceptance belong to the root orchestrator.
+- The audit loop is unchanged: re-audit resumes the same sessions; short audit
+  sessions do not threaten the budget.
+
+Rule of thumb: delegate **investigation** broadly, **implementation** narrowly,
+keep **integration** centralized.
+
+## 3. Tool batching
+
+Every turn re-sends the whole prompt. One tool per turn multiplies the budget by
+the number of small steps.
+
+- ≥ 3 independent commands per turn, or one script instead of five to ten calls.
+- Move long WSL commands into a wrapper script: a 250-character line in every turn
+  costs more than a file read once.
+- For file reads use `read` with `limit`/`offset`, not a full `cat`.
+- Target metric: ≥ 2 tools per turn.
+
+## 4. Tool output
+
+- Anything over 20k chars goes to a file; context gets the head (4k) and the path.
+  The guard does this automatically for `shell`, `bash`, `webfetch`.
+- Screenshots and binary attachments are files plus a path, never base64 in
+  context.
+- `execute` (Code Mode) is not capped by the guard: limit the result in the script
+  itself — return a summary and a path, not hundreds of kilobytes of raw JSON.
+- `read`, `write`, `edit` and the kit's own tools are not capped: they have their
+  own contract, and losing content breaks the work.
+
+## 5. State in files
+
+- `handoff` — the required output of a slice (template below); default path
+  `docs/planning/handoff-<YYYY-MM-DD>.md`, the project root when the directory
+  does not exist.
+- `decisions` — decisions and reasons; one decision per entry; default path
+  `docs/planning/decisions-<YYYY-MM-DD>.md`.
+- `state` — branch, gates, open risks, the next three steps; refreshed before a
+  new session; default path `docs/planning/state.md`.
+- A new session starts from `state` and the target SPEC section, not from a
+  retelling of the previous session.
+
+## 6. Models
+
+- Default to the cheap model; the expensive one only for architecture decisions,
+  reviews and dispute resolution.
+- Document edits, reading and mechanical checks do not need an expensive model.
+- Measurement: 223 turns of the expensive model cost $63, 104 turns of the cheap
+  one cost $0.09. One model switch saves more than any prompt tweak. This is an
+  internal measurement of a consumer project: the artifact is not attached to the
+  repository, and the figures are not reproducible from it.
+
+## 7. Metrics
+
+| Metric | Target | Where |
+| --- | --- | --- |
+| Estimated prompt (median) | ≤ 150k | `orch_uni_session_stats` |
+| Compactions per slice | ≤ 1 | `orch_uni_session_stats` |
+| Tools per turn (`toolCalls/requests`, reported as `toolsPerTurn`) | ≥ 2 | `orch_uni_session_stats` |
+| Share of capped outputs among the tool's calls (`toolOutputsCappedByTool.shell / toolCallsByTool.shell`; likewise `bash`, `webfetch`) | < 5% | `orch_uni_session_stats` |
+| Handoff at slice end | present | working tree |
+
+`orch_uni_session_stats` reports the counters of the current plugin instance and
+the configured limits; historical runs are counted from the session database on
+the project side.
+
+## 8. Guard
+
+The guard is a set of plugin hooks plus a compaction-event subscription, not a
+set of bans:
+
+- `session.context` — estimates the prompt and adds one short reminder when it
+  crosses a budget level. The reminder is injected once at a level transition,
+  not on every request; within a level the text is stable, so the prefix cache is
+  not broken.
+- compaction events — the `session.compaction` hook is registered on every host:
+  it counts attempts (`compactionAttempts`) and sends a tentative note to the
+  nearest request when the terminal event is delayed; the note names no
+  compaction number and claims no limit. Only `session.compaction.ended`
+  confirms a compaction (deduplicated by `event.id` or the durable position);
+  only it moves `compactions` and the limit. `session.compaction.failed`
+  increments `compactionFailures`, drops the tentative note and keeps a
+  confirmed note that is still waiting for delivery. When the event stream ends
+  or throws, the guard reports `eventLive: false`, `compactionSource: "hook"` and
+  `streamFailures: 1` (the per-session `errors` stays `0`); the hook is already
+  registered, so attempts keep counting, while no confirmed compaction or stop
+  signal is invented — no false "limit reached" on that path. `guard` exposes
+  the source, liveness and stream failures.
+- `tool.execute.after` — caps the output of the configured tools and stores the
+  full text in a private per-process root
+  `os.tmpdir()/opencode-tool-output-<random>/` (POSIX 0700 for the root and the
+  session directory, 0600 for the file). Windows ignores mode (measured: 0666 for
+  the root, the session directory and the file): privacy there rests on the ACL of
+  `os.tmpdir()` and is not checked by code. The root is created
+  with `mkdtemp` at setup, so a pre-created directory or junction named
+  `opencode-tool-output` is never used; on POSIX the root must belong to the
+  current uid with no group/other access, otherwise the guard disables itself with
+  a warning (fail-open: the result is untouched). Session directories (`s-<uuid>`)
+  and files (`c-<uuid>.txt`, written with `wx`) are random, and each `realpath` is
+  proven inside the root; the root is removed when the plugin unloads (best
+  effort). A string with a lone surrogate is normalized once (U+FFFD), so the
+  file, the head and the counters describe the same string. Residual risk
+  accepted: a same-user attacker can still swap a session
+  directory between `realpath` and `writeFile` (Node has no `openat`). If `TMPDIR`
+  points inside the workspace, the files land there.
+
+Configuration (defaults):
+
+```jsonc
+{
+  "sessionGuard": {
+    "enabled": true,
+    "promptTokensSoft": 150000,
+    "maxCompactions": 1
+  },
+  "toolOutputGuard": {
+    "enabled": true,
+    "maxChars": 20000,
+    "headChars": 4000,
+    "tools": ["shell", "bash", "webfetch"]
+  }
+}
+```
+
+`maxCompactions: 0` disables the compaction limit. `guard.toolOutputEnabled` is
+`true` only when the private root exists **and** the effective tool list is not
+empty; `guard.toolOutputTools` is that list (normalized, protected and kit names
+removed) and `guard.unkeyedCalls` counts hook calls without a non-empty
+`sessionID` (such input is dropped, not bucketed under `""`). An empty `tools`
+list — explicit or after every entry was rejected — disables capping with a
+warning. Accepted limits: a session directory `s-<uuid>` lives until the plugin
+unloads — it is removed neither on `session.deleted` nor after a refused cap
+(a readonly result, for example) and is released with the root; lone-surrogate
+normalization relies on ES2024 `String.prototype.isWellFormed`/`toWellFormed`
+(the minimum runtime version is not pinned in `engines`, so on an old runtime the
+cap degrades fail-open: `errors` +1, the result is untouched).
+In the counters, `toolCalls`
+and the per-tool counters include nested Code Mode calls, and `outputCharsSaved`
+is an upper estimate in characters (the injected stub is subtracted).
+`toolCallsByTool` and `toolOutputsCappedByTool` split calls and capped outputs by
+the normalized tool name (namespace stripped, lower-case). Duplicate compaction
+events are counted once only when the host supplies `event.id` or a durable
+position; without either identity a re-delivered event may be counted again
+(fail-open in the direction of counting).
+
+The guard is fail-open: a hook error neither breaks the request nor corrupts the
+tool result. It writes nothing to the working tree (except when `TMPDIR` points
+inside the workspace — see above) and blocks nothing — it only reminds and caps
+output. Either part can be disabled with its `enabled` flag.
+
+## Handoff template
+
+```md
+# Handoff: <slice> — <YYYY-MM-DD>
+
+<!-- File: docs/planning/handoff-<YYYY-MM-DD>.md; use the project root when the directory is absent. -->
+
+## Goal and DoD
+One sentence of the goal and a verifiable definition of done.
+
+## Done
+- What changed; what proves it (command, test, commit).
+
+## Not done
+- What remains and why (blocker, owner decision, next wave).
+
+## Decisions
+- Decision — reason; link to the document or commit.
+
+## Risks and limits
+- Accepted risk — by whom and until when.
+
+## Next step
+One concrete action for the next session.
+```
+
+## Slice checklist
+
+- [ ] The slice is closed by DoD, not by "ran out of time".
+- [ ] The handoff is written and references evidence.
+- [ ] Decisions and risks are in files, not only in chat.
+- [ ] The working tree is clean or explicitly described in the handoff.
+- [ ] The next session starts from `state` and SPEC, not from a retelling.

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` (общий для всех шагов)
 
 ```

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-оркестратору.
+- Аудиторский цикл не меняется: 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,6 +53,7 @@ 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"
 
 /** Stable plugin id: diagnostics, enable/disable selectors, storage scope. */
@@ -118,10 +119,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 +356,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 +411,38 @@ 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)
+  let toolsCleanup: () => void
+  try {
+    toolsCleanup = await registerAuditTools(ctx, { sessionBudget })
+  } catch (error) {
+    await sessionBudget.cleanup()
+    throw error
+  }
   let commandsCleanup: Plugin.Cleanup
   try {
     commandsCleanup = await registerKitCommands(ctx, locale)
   } catch (error) {
     toolsCleanup()
+    await sessionBudget.cleanup()
     throw error
   }
   return async () => {
     try {
       await commandsCleanup()
     } finally {
-      toolsCleanup()
+      try {
+        toolsCleanup()
+      } finally {
+        await sessionBudget.cleanup()
+      }
     }
   }
 }