opencode-orchestrator-uni 0.4.0 → 0.5.0

package/README.md

@@ -12,10 +12,10 @@ ships the **orchestrator agent kit**:
 - `fix-runner` — the only writing subagent (applies the "to close" list);
 - the kit's process documents, exposed as the **`audit-kit` reference**
   (`call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`,
-  `instruction-other-session.md`, `context-efficiency.md`);
-- four deterministic, read-only tools — `orch_uni_validate_report`, `orch_uni_context_lint`,
-  `orch_uni_snapshot`, `orch_uni_sessions` (see [Tools](#tools));
-- two slash commands — `/agents-md` and `/spec` (see [Commands](#commands)).
+  `instruction-other-session.md`, `context-efficiency.md`, `session-discipline.md`);
+- five deterministic, read-only tools — `orch_uni_validate_report`, `orch_uni_context_lint`,
+  `orch_uni_snapshot`, `orch_uni_sessions`, `orch_uni_session_stats` (see [Tools](#tools));
+- three slash commands — `/agents-md`, `/spec` and `/handoff` (see [Commands](#commands)).
 
 Read-only audit agents are enforced by `edit: deny` plus the prompt ban; their shell
 permission stays allowed so they can run verification commands (an accepted risk, no
@@ -55,8 +55,8 @@ directory (see [Locale](#locale)). OpenCode lists it in session context as an
 additional local directory, so the orchestrator (and any other agent) can read
 the process documents directly, for example `<reference path>/call-mechanics.md`.
 
-The plugin also registers four deterministic, **read-only** tools in the `orch_uni`
-namespace and two slash commands — see [Tools](#tools) and [Commands](#commands).
+The plugin also registers five deterministic, **read-only** tools in the `orch_uni`
+namespace and three slash commands — see [Tools](#tools) and [Commands](#commands).
 
 ## Commands
 
@@ -64,6 +64,7 @@ namespace and two slash commands — see [Tools](#tools) and [Commands](#command
 | --- | --- |
 | `/agents-md` | Injects the AGENTS.md audit/draft workflow: `context-efficiency.md` template, `orch_uni_context_lint`, `context-lint`, approval before writing. |
 | `/spec` | Injects the SPEC.md workflow: brief, clarifying questions, EARS/AC/traceability, `orch_uni_context_lint`, `context-lint`, approval before writing. |
+| `/handoff` | Injects the slice-closing workflow: session and working-tree facts, the `session-discipline.md` handoff template, writes `docs/planning/handoff-<YYYY-MM-DD>.md`. |
 
 A command is a prompt, not a writer: its handler injects a workflow prompt into the
 current session. The orchestrator then follows the usual evidence and approval rules.
@@ -76,10 +77,11 @@ current session. The orchestrator then follows the usual evidence and approval r
 | `orch_uni_context_lint`     | yes       | Deterministic audit of AGENTS.md/SPEC.md: budget, vague phrases, links, sections |
 | `orch_uni_snapshot`         | yes       | Deterministic revision of a directory tree (per-file sha256 + aggregate hash)  |
 | `orch_uni_sessions`         | yes       | Child sessions of a session: agent, model, cost, tokens, time                  |
+| `orch_uni_session_stats`    | yes       | Session protocol counters: prompt, compactions, tools/turn, capped outputs      |
 
 Every tool answers with a JSON text body. Failures are **typed codes** inside the body
 (`E_INPUT`, `E_NO_JSON`, …) instead of thrown tool errors, so an agent can branch on the
-code without parsing prose. None of the four writes to the workspace, the session store
+code without parsing prose. None of the five writes to the workspace, the session store
 or the configuration.
 
 ### `orch_uni_validate_report`
@@ -261,6 +263,134 @@ picks up fixture trees such as `eval/`; pass an explicit path for the canonical
 `E_INPUT` for malformed arguments, `E_NOT_FOUND` when the parent session does not exist,
 `E_ABORTED` when the session is stopped.
 
+### `orch_uni_session_stats`
+
+```jsonc
+{}                                  // counters of the calling session
+{ "sessionID": "ses_…" }            // any session on this server, not only a child
+```
+
+```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` may name **any session on this server**, not only a child of the caller;
+that is deliberate — the orchestrator uses the report to control every slice it runs.
+Counters are per plugin instance, and `tracked` is `true` once any event or hook
+observed the session; a `session.deleted` event forgets it. `band` is the highest
+budget level reached (`0` below the soft threshold); `promptTokensMedian` is the
+median over the last 256 requests; `toolCalls` and the per-tool counters include
+nested Code Mode calls; `toolCallsByTool` and `toolOutputsCappedByTool` split calls
+and capped outputs by the normalized tool name (namespace stripped, lower-case);
+`outputCharsSaved` is a character count, not bytes, and an upper estimate (the
+injected stub is subtracted). `compactions` counts confirmed
+`session.compaction.ended` events only; `compactionAttempts` counts every
+`session.compaction` hook call, so on a host with a dead or absent event stream
+attempts keep growing while `compactions` and `compactionLimitReached` stay put (a
+failed attempt is never a stop signal). A dead stream is reported once in
+`guard.streamFailures`; the per-session `errors` counts hook failures only, so a
+transport incident is not attributed to every session. 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). A
+session the store does not return and this instance never observed is
+`E_NOT_FOUND` (recognized by the typed `_tag`/`name`/`code` — `Session.NotFoundError`,
+`SessionNotFoundError`, `NotFoundError`, `ENOENT` — with a narrow message fallback);
+`session.get` returning `undefined` for an untracked session is the same not-found
+answer; a transient `session.get` failure (a lock, permission, `unknown database`) is
+`E_INTERNAL`; a known session with zero requests is a valid report with
+`tracked: false`. Without `session.get`,
+an untracked session is `E_NO_API`, a tracked one is `ok` with `session: null` and a
+`limitations` entry. Codes: `E_INPUT`, `E_NOT_FOUND`, `E_INTERNAL`, `E_NO_API`,
+`E_UNAVAILABLE` (the guard is not registered or its hooks failed), `E_ABORTED`.
+
+## Session hygiene
+
+The plugin implements the [`session-discipline.md`](./docs/en/session-discipline.md)
+protocol: a session is one slice, the prompt budget is ≤150k tokens, at most one
+compaction, tool output goes to a file, and a slice ends with a handoff.
+
+The runtime part is three hooks (`session.context`, `session.compaction`,
+`tool.execute.after`) plus a compaction-event subscription:
+
+- `session.context` — estimates the prompt (system + messages) and, when it crosses
+  a budget level, adds one short reminder. The reminder is injected **once, when a
+  new level is crossed**, 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; 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) and raises a confirmed note with the number and the limit;
+  `session.compaction.failed` increments `compactionFailures`, drops the tentative
+  note and keeps a confirmed note that is still waiting for delivery. If the event
+  stream ends or throws, `guard.eventLive` turns `false`,
+  `guard.compactionSource` becomes `hook` and `guard.streamFailures` becomes `1`
+  (the per-session `errors` stays `0`); the hook keeps counting attempts, but no
+  confirmed compaction and no false "limit reached" is invented on that path.
+- `tool.execute.after` — for `shell`, `bash`, `webfetch` it caps output over
+  `maxChars`: the full text goes to 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),
+  so privacy there rests on the ACL of `os.tmpdir()` and is not checked by code.
+  The model gets a head and the path; the root is created with `mkdtemp` at plugin
+  setup, so a
+  pre-created `opencode-tool-output` directory or junction 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: results are 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 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 instead. `read`, `write`, `edit`, `execute` and the kit's own tools are
+  not capped, and a kit tool named without its namespace (`session_stats`) is
+  refused in the config with a warning.
+
+`maxCompactions: 0` disables the compaction limit. The guard is fail-open: a hook
+error neither breaks the request nor corrupts the result. Either part can be
+disabled with its `enabled` flag:
+
+```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"]
+        }
+      }
+    }
+  ]
+}
+```
+
+Slice metrics — `orch_uni_session_stats`; closing a slice — the `/handoff` command.
+
 ## Models
 
 Agent definitions carry no `model`; models are configured on the plugin entry in
@@ -408,7 +538,7 @@ npm run lint:fix     # biome check --write . (applies safe fixes)
 
 The `check:locales` and `verify:kit` scripts need a git checkout of the kit — the npm package ships no `tools/` directory, so in an installed package they are unavailable (`stand: unavailable` plus your own reproducible checks).
 
-`npm test` scans only `./test/` — the shipped suite (289 tests in 9 files, up from
+`npm test` scans only `./test/` — the shipped suite (400 tests in 10 files, up from
 72 in 5 before the identifier guards). A bare `bun test` from the repository root is red by
 design: the positional argument of `bun test` is a path substring filter, so the
 bare command also picks up the intentionally failing fixtures under `eval/cases/`

package/README.ru.md

@@ -12,11 +12,11 @@
 - `fix-runner` — единственный пишущий субагент (применяет список «к закрытию»);
 - процессные документы комплекта, доступные как **reference `audit-kit`**
   (`call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`,
-  `instruction-other-session.md`, `context-efficiency.md`);
-- четыре детерминированных read-only инструмента — `orch_uni_validate_report`,
-  `orch_uni_context_lint`, `orch_uni_snapshot`, `orch_uni_sessions`
-  (см. [Инструменты](#инструменты));
-- две слэш-команды — `/agents-md` и `/spec` (см. [Команды](#команды)).
+  `instruction-other-session.md`, `context-efficiency.md`, `session-discipline.md`);
+- пять детерминированных read-only инструментов — `orch_uni_validate_report`,
+  `orch_uni_context_lint`, `orch_uni_snapshot`, `orch_uni_sessions`,
+  `orch_uni_session_stats` (см. [Инструменты](#инструменты));
+- три слэш-команды — `/agents-md`, `/spec` и `/handoff` (см. [Команды](#команды)).
 
 Read-only аудиторы держатся на `edit: deny` плюс запрете в промпте; shell-разрешение
 остаётся, чтобы запускать проверки (принятый риск, ни одно разрешение не ослаблено).
@@ -57,8 +57,8 @@ Reference `audit-kit` указывает на per-locale каталог `docs/<l
 может читать процессные документы напрямую, например
 `<reference path>/call-mechanics.md`.
 
-Плагин также регистрирует четыре детерминированных **read-only** инструмента в
-пространстве имён `orch_uni` и две слэш-команды — см. [Инструменты](#инструменты)
+Плагин также регистрирует пять детерминированных **read-only** инструментов в
+пространстве имён `orch_uni` и три слэш-команды — см. [Инструменты](#инструменты)
 и [Команды](#команды).
 
 ## Команды
@@ -67,6 +67,7 @@ Reference `audit-kit` указывает на per-locale каталог `docs/<l
 | --- | --- |
 | `/agents-md` | Вставляет workflow аудита/черновика AGENTS.md: шаблон `context-efficiency.md`, `orch_uni_context_lint`, `context-lint`, подтверждение перед записью. |
 | `/spec` | Вставляет workflow SPEC.md: бриф, уточняющие вопросы, EARS/AC/трассировка, `orch_uni_context_lint`, `context-lint`, подтверждение перед записью. |
+| `/handoff` | Вставляет workflow закрытия среза: факты сессии и рабочего дерева, шаблон handoff из `session-discipline.md`, запись `docs/planning/handoff-<YYYY-MM-DD>.md`. |
 
 Команда — это промпт, а не писатель: обработчик вставляет workflow-промпт в
 текущую сессию. Дальше оркестратор работает по обычным правилам evidence и
@@ -80,10 +81,11 @@ Reference `audit-kit` указывает на per-locale каталог `docs/<l
 | `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`
@@ -263,6 +265,136 @@ Commands, HTML-комментарий вроде `<!-- npm install -->` кома
 `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`](./docs/ru/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`; модели настраиваются у записи плагина в
@@ -414,7 +546,7 @@ npm run lint:fix     # biome check --write . (применяет безопас
 
 Команды `check:locales` и `verify:kit` требуют git-чекаута комплекта — в npm-пакете каталог `tools/` не поставляется, поэтому в установленном пакете они недоступны (`stand: unavailable` и собственные воспроизводимые проверки).
 
-`npm test` сканирует только `./test/` — поставляемый набор (289 тестов в 9 файлах;
+`npm test` сканирует только `./test/` — поставляемый набор (400 тестов в 10 файлах;
 до стражей идентификаторов было 72 в 5). Голый `bun test` из корня репозитория
 красный по замыслу: позиционный аргумент `bun test` — это фильтр-подстрока пути,
 поэтому голая команда подхватывает и специально падающие фикстуры в

package/agents/en/orchestrator.md

@@ -26,6 +26,15 @@ GENERAL CYCLE:
 6. Drive it to the end: fixes → re-check → until the criteria are met. No "left for later" without an explicit record to the owner.
 7. Outcome: a short summary — what was done, what confirms it, what remains or was accepted as a risk.
 
+SESSION HYGIENE (the `session-discipline.md` protocol):
+- One slice = one session. Budget: estimated prompt ≤150k tokens, ≤1 compaction; when the limit is reached — `/handoff`, commit and a new session, no pushing on.
+- Investigation and verification go to subagents (clean context, 1–2k tokens returned); implementation goes to one writer; consolidation and decisions are yours.
+- Batching: ≥3 independent commands per turn or one script; for reads use `read` with `limit`/`offset`, not `cat`.
+- Output over 20k chars — to a file and a path; screenshots — as a file, not base64; in `execute` limit the result yourself.
+- Default to the cheap model; the expensive one only for decisions and reviews.
+- At the end of a slice — a handoff per the template and a commit; the next session starts from `state` and SPEC.
+- Slice metrics — `orch_uni_session_stats` (prompt, compactions, tools/turn, capped outputs).
+
 The AUDIT MODE turns on when the task is to verify a change (diff/PR/range), a plan (document/ADR) or a release (tag/publication): the loop through to full ready per the kit's documents (`call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`, `instruction-other-session.md`) — in the kit's directory (the directory is set by the owner/the task). If the documents are unavailable — work by the inline skeleton below and tell the owner. Release gates = publication of a release/tag; at these gates `meta` (`meta`) is mandatory.
 - Chain: staleness fact-check (`factcheck`) → the `empiric` ∥ `invariant` pair → arbiter (`arbiter`) on discrepancies → fixes → re-audit of the same sessions → until full ready; at release gates — `redteam` and `meta`.
 - Restricted environment (Code Mode: actions only via `execute`+directory, `subagent`/direct tools unavailable): before the audit phase, check that `subagent` is available; if not — do not start the loop. The outcome in such an environment is "done; the regular audit is deferred" (state revision + compensating checks as a list + a plan for a run in a normal session); a self-check and an `ai` review do not count as an audit (details — `call-mechanics.md` §8).

package/agents/ru/orchestrator.md

@@ -26,6 +26,15 @@ permissions:
 6. Доводи до конца: исправления → повторная проверка → пока критерии не выполнены. Без «оставил на потом» без явной фиксации владельцу.
 7. Итог: краткая сводка — что сделано, чем подтверждено, что осталось или принято как риск.
 
+ГИГИЕНА СЕССИИ (протокол `session-discipline.md`):
+- Один срез = одна сессия. Бюджет: оценка промпта ≤150k токенов, ≤1 компакция; при пороге — `/handoff`, коммит и новая сессия, без «дожимания».
+- Разведка и проверка — субагентам (чистый контекст, ответ 1–2k токенов); реализация — одному писателю; сведение и решения — тебе.
+- Батчинг: ≥3 независимых команд за ход или один скрипт; для чтения — `read` с `limit`/`offset`, а не `cat`.
+- Вывод >20k символов — в файл и путём; скриншоты — файлом, не base64; в `execute` ограничивай результат сам.
+- Модель по умолчанию — дешёвая; дорогая — только решения и ревью.
+- В конце среза — handoff по шаблону и commit; следующая сессия стартует с `state` и SPEC.
+- Метрики среза — `orch_uni_session_stats` (промпт, компакции, тулы/ход, урезанные выводы).
+
 АУДИТОРСКИЙ РЕЖИМ включается, когда задача — проверить изменение (diff/PR/диапазон), план (документ/ADR) или релиз (тег/публикация): цикл до полного ready по документам комплекта (`call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`, `instruction-other-session.md`) — в каталоге комплекта (каталог задаётся владельцем/заданием). Если документы недоступны — работай по инлайн-скелету ниже и сообщи владельцу. Релизные ворота = публикация релиза/тега; при них мета (`meta`) обязательна.
 - Цепочка: факт-чек актуальности (`factcheck`) → пара `empiric` ∥ `invariant` → арбитр (`arbiter`) на расхождения → правки → повторный аудит тех же сессий → до полного ready; на релизных воротах — `redteam` и `meta`.
 - Ограниченная среда (Code Mode: действия только через `execute`+каталог, `subagent`/прямые инструменты недоступны): перед аудиторской фазой проверь наличие `subagent`; нет — цикл не запускай. Итог в такой среде — «готово; штатный аудит отложен» (ревизия + компенсирующие проверки списком + план прогона в обычной сессии); самопроверка и `ai`-ревью аудитом не называются (детали — `call-mechanics.md` §8).

package/docs/en/root-runbook.md

@@ -5,6 +5,8 @@
 - **Root (the primary agent)** — does not audit: forms the brief, launches subagents, consolidates the reports; for the "unprovable" — the owner's decision: the root frames the question, records the risk and escalates. Maintains the registry of accepted risks, makes fixes as separate commits, decides on "ship".
 - **Subagents** (read-only): `factcheck`, `empiric`, `invariant`, `arbiter`, (at the gates) `redteam`, `meta`.
 
+Slice session hygiene — boundaries, context budget (≤150k tokens, ≤1 compaction) and the handoff — in `session-discipline.md`.
+
 ## Brief template `case-<id>.md` (common to all steps)
 
 ```