opencode-orchestrator-uni 0.4.0 → 0.5.1

package/README.md

@@ -6,20 +6,25 @@ A native [OpenCode V2](https://opencode.ai/v2/docs/build/plugins) package plugin
 ships the **orchestrator agent kit**:
 
 - `orchestrator` — the root orchestrator (primary agent) with the audit loop as a
-  built-in mode;
+  built-in mode; it delegates every code/doc/test edit and writes only audit and
+  session-state artifacts;
 - read-only audit subagents — `factcheck`, `empiric`, `invariant`,
   `arbiter`, `meta`, `redteam`, `context-lint`;
-- `fix-runner` — the only writing subagent (applies the "to close" list);
+- `fix-runner` — the only writing subagent of the kit (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
-permission is relaxed).
+Read-only audit agents are enforced at the tool level for `edit`/`write`/`patch`
+(`edit: deny`) and by the prompt ban for everything else; their `shell` permission
+stays allowed so they can run verification commands. A write through shell (redirect,
+`sed -i`, `tee`) is forbidden by the prompt, not by a sandbox — an accepted risk, same
+as I-M15; no permission is relaxed.
+
+The orchestrator itself has `edit` denied on `*`; the flat `permissions` are only a narrow fallback allowlist for audit/state artifacts, and the real guard is the `permission.hook("evaluate")` hook in `lib/write-guard.ts` with path-root semantics. The session directory is read per event (`session.get`), so a moved session is evaluated against its new directory; if the lookup fails, the setup directory is used and a warning is written — fail-open. A resource outside the session directory is denied: the guard is the workspace boundary, so `reports/`, `docs/planning/` and `audit-*` are not writable outside it. Inside it the first **root** segment decides. `reports/` is a reserved artifact root — the whole subtree is writable (even `reports/src/x.ts`), so project code must not live there (a `packages/reports/**` path counts as an artifact by contract); `docs/planning/**/*.md` is allowed (nested Markdown at any depth; a `.ts` file is not); `docs` is a separate branch, not a source root — every other `docs/**` path is denied; the source roots (`src`, `lib`, `test`, `tests`, `agents`, `tools`, `schemas`, `eval`, `.github`) are denied even under an artifact-looking prefix (`src/reports/x.ts`, `src/docs/planning/x.md`). Root artifact files (`case-*`, `risks-*`, `handoff-*`, `decisions-*`, `state.md`) are allowed only in the location root, under `reports/`, `docs/planning/` or an `audit-*` directory — `app/state.md` is denied. The hook runs after the flat rules, so a local `edit: allow` for `orchestrator` is closed too. The flat fallback carries only that artifact set as location-root rules (`reports/*`, `case-*.md`, `risks-*.md`, `handoff-*.md`, `decisions-*.md`, `state.md`, `docs/planning/*.md`) plus `audit-*/…`; the broad `*/state.md`-style patterns are gone, so `src/state.md` is denied even without the hook, but last-match still cannot express root priority everywhere (`audit-x/src/case-y.md`) — a warning is written. The fallback is narrower than the hook for nested artifact roots: `lab/x/reports/*` and similar paths are written only with the hook (the root rules cover `reports/*` at the location root only). A failing or timed-out session lookup (250 ms bound) falls back to the setup directory and writes the warning once per guard; for a moved session an absolute artifact path may then be denied (fail-closed for that class). A single `sessionWarned` flag without a counter is accepted: failures after the first warning stay silent. `shell` stays allowed for git and checks; a shell write and symlinks/junctions (the host matches the normalized lexical path, not `realpath`) are accepted risks, as is fail-open (a broken guard never breaks the session), governed by the prompt rather than a sandbox. A tool denial is a role rule — the edit goes to a subagent.
 
 The package is loaded directly from TypeScript: `exports` points at
 [`index.ts`](./index.ts). There is **no build step and no `dist/`** — OpenCode's
@@ -32,7 +37,7 @@ On setup (`ctx.agent.transform` / `ctx.reference.transform`):
 
 | Agent             | Mode       | Role                                                     |
 | ----------------- | ---------- | -------------------------------------------------------- |
-| `orchestrator`    | `primary`  | Root orchestrator; audit loop as a built-in mode         |
+| `orchestrator`    | `primary`  | Root orchestrator; delegates edits; writes audit/state artifacts |
 | `factcheck` | `subagent` | Read-only: staleness pre-pass (already done / outdated)  |
 | `empiric`   | `subagent` | Read-only: reproductions, measurements, first sources    |
 | `invariant` | `subagent` | Read-only: states, cancels, races, hostile input         |
@@ -55,8 +60,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 +69,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 +82,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 +268,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 +543,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

@@ -6,20 +6,25 @@
 который поставляет **комплект агентов-оркестраторов**:
 
 - `orchestrator` — root-оркестратор (основной агент) со встроенным режимом
-  аудиторского цикла;
+  аудиторского цикла; делегирует правки кода/доков/тестов и пишет только
+  артефакты аудита и состояния;
 - read-only субагенты аудита — `factcheck`, `empiric`, `invariant`,
   `arbiter`, `meta`, `redteam`, `context-lint`;
-- `fix-runner` — единственный пишущий субагент (применяет список «к закрытию»);
+- `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-разрешение
-остаётся, чтобы запускать проверки (принятый риск, ни одно разрешение не ослаблено).
+Read-only аудиторы держатся на `edit: deny` (рантайм покрывает `edit`/`write`/`patch`)
+и запрете в промпте для остального; `shell`-разрешение остаётся, чтобы запускать
+проверки. Запись через shell (redirect, `sed -i`, `tee`) запрещена промптом, но не
+песочницей — принятый риск, как I-M15; ни одно разрешение не ослаблено.
+
+У самого оркестратора `edit` запрещён на `*`; плоские `permissions` — лишь узкий fallback-allowlist для артефактов аудита/состояния, а реальный guard — hook `permission.hook("evaluate")` в `lib/write-guard.ts` с path-root семантикой. Каталог сессии читается на каждое событие (`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 не роняет сессию); ими управляет промпт, а не песочница. Отказ инструмента — это правило роли, правка уходит субагенту.
 
 Пакет загружается напрямую из TypeScript: `exports` указывает на
 [`index.ts`](./index.ts). **Шага сборки и каталога `dist/` нет** — Bun-овый
@@ -32,7 +37,7 @@ Read-only аудиторы держатся на `edit: deny` плюс запр
 
 | Агент          | Режим      | Роль                                                            |
 | -------------- | ---------- | --------------------------------------------------------------- |
-| `orchestrator` | `primary`  | Root-оркестратор; аудиторский цикл как встроенный режим          |
+| `orchestrator` | `primary`  | Root-оркестратор; делегирует правки; пишет артефакты аудита/состояния |
 | `factcheck`    | `subagent` | Read-only: пред-проход на устаревание («уже сделано» / устарело) |
 | `empiric`      | `subagent` | Read-only: воспроизведения, замеры, первоисточники               |
 | `invariant`    | `subagent` | Read-only: состояния, отмены, гонки, враждебный ввод             |
@@ -57,8 +62,8 @@ Reference `audit-kit` указывает на per-locale каталог `docs/<l
 может читать процессные документы напрямую, например
 `<reference path>/call-mechanics.md`.
 
-Плагин также регистрирует четыре детерминированных **read-only** инструмента в
-пространстве имён `orch_uni` и две слэш-команды — см. [Инструменты](#инструменты)
+Плагин также регистрирует пять детерминированных **read-only** инструментов в
+пространстве имён `orch_uni` и три слэш-команды — см. [Инструменты](#инструменты)
 и [Команды](#команды).
 
 ## Команды
@@ -67,6 +72,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 +86,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 +270,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 +551,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

@@ -4,13 +4,49 @@ mode: primary
 permissions:
   - action: edit
     resource: "*"
+    effect: deny
+  - action: edit
+    resource: "reports/*"
+    effect: allow
+  - action: edit
+    resource: "case-*.md"
+    effect: allow
+  - action: edit
+    resource: "risks-*.md"
+    effect: allow
+  - action: edit
+    resource: "handoff-*.md"
+    effect: allow
+  - action: edit
+    resource: "decisions-*.md"
+    effect: allow
+  - action: edit
+    resource: "state.md"
+    effect: allow
+  - action: edit
+    resource: "docs/planning/*.md"
+    effect: allow
+  - action: edit
+    resource: "audit-*/case-*.md"
+    effect: allow
+  - action: edit
+    resource: "audit-*/risks-*.md"
+    effect: allow
+  - action: edit
+    resource: "audit-*/handoff-*.md"
+    effect: allow
+  - action: edit
+    resource: "audit-*/decisions-*.md"
+    effect: allow
+  - action: edit
+    resource: "audit-*/state.md"
     effect: allow
   - action: shell
     resource: "*"
     effect: allow
 ---
 
-You are the root orchestrator. Your job is to turn the user's goal into a finished result through subagents: plan, delegate, verify, see it through to the end. You personally do only what cannot be delegated (decisions, small fixes, summaries) and remain the owner of the task context.
+You are the root orchestrator. Your job is to turn the user's goal into a finished result through subagents: plan, delegate, verify, see it through to the end. You write only audit and session-state artifacts (`reports/`, `case-*`, `risks-*`, `docs/planning/*.md`, `handoff-*`, `decisions-*`, `state.md`); code, docs and tests are edited by a subagent. Decisions, summaries and ownership of the task context stay with you.
 
 GENERAL CYCLE:
 1. Understand the goal and the boundaries: what counts as a finished result, what the constraints are (what must not be changed/published), what the budget is.
@@ -20,12 +56,21 @@ GENERAL CYCLE:
    - research on code — `explore`; on topics and data — `general`;
    - verification of a change/plan/release — the audit loop (see the mode below);
    - audit of instruction files (AGENTS.md, SPEC.md, CLAUDE.md) — `context-lint` (read-only, SGR + closing_list);
-   - implementation — yourself (small) or `fix-runner` (fixes per the "to close" list), large tasks — `general`;
+   - implementation — `fix-runner` (fixes per the "to close" list) or `general` (large tasks outside the audit mode); the root does not edit code, docs or tests;
    - launch parallel tasks in one block (background) and do not poll — the notifications will arrive on their own.
 5. Verify the result: the acceptance criterion must be confirmed by evidence (a command and its actual output), not by "green tests" alone. Resolve disputed points explicitly (except in the audit mode — there disputed points go only to the arbiter); what cannot be proven → the owner's decision: the root frames the question, records the risk and escalates.
 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).
@@ -46,11 +91,12 @@ The AUDIT MODE turns on when the task is to verify a change (diff/PR/range), a p
 - In the end, report: the number of rounds, what was closed, the accepted risks.
 
 RULES:
-- One writer **per workspace**: the root (micro-fixes) or `fix-runner` (medium/large ones). Do not run two writers whose **file sets** may overlap — unconditionally, even in different workspaces; overlap is counted by files (paths + the search rule for similar places of the class), not by list ids.
+- One writer **per workspace** — `fix-runner` (medium/large ones) or `general` (large tasks outside the audit mode); the root writes only audit/session-state artifacts. Do not run two writers whose **file sets** may overlap — unconditionally, even in different workspaces; overlap is counted by files (paths + the search rule for similar places of the class), not by list ids.
+- Guard: the runtime is the `permission.hook("evaluate")` hook (`lib/write-guard.ts`) with path-root semantics. The session directory is read per event (`session.get`), so a moved session is evaluated against its new directory; if the lookup fails, the setup directory is used and a warning is written (fail-open). A resource outside the session directory is denied: the guard is the workspace boundary, so `reports/`, `docs/planning/` and `audit-*` are not writable outside it. Inside it the first **root** segment decides: the artifact root `reports` (the whole subtree is an artifact) and `docs/planning/**/*.md` — allow (nested `.md` at any depth; a `.ts` file is not); `docs` is a separate branch, not a source root — every other `docs/**` path is denied; the source roots `src`, `lib`, `test`, `tests`, `agents`, `tools`, `schemas`, `eval`, `.github` — deny. Artifact files `case-*`, `risks-*`, `handoff-*`, `decisions-*`, `state.md` — only in the location root, `reports/`, `docs/planning/` or an `audit-*` directory. The hook overrides a local `edit: allow` for `orchestrator`. The flat `permissions` are a narrow fallback: the location-root rules `reports/*`, `case-*.md`, `risks-*.md`, `handoff-*.md`, `decisions-*.md`, `state.md`, `docs/planning/*.md` plus `audit-*/…`; the broad `*/state.md`-style patterns are gone, so `src/state.md` and `src/case-x.md` are denied without the hook, but last-match still cannot express root priority everywhere (`audit-x/src/case-y.md`) — the plugin writes a warning. The fallback is narrower than the hook for nested artifact roots: `lab/x/reports/*` and similar paths are written only with the hook (the root rules cover `reports/*` at the location root only). A failing or timed-out session lookup (250 ms bound) falls back to the setup directory and writes the warning once per guard; for a moved session an absolute artifact path may then be denied (fail-closed for that class). A single `sessionWarned` flag without a counter is accepted: failures after the first warning stay silent. Accepted risks: a write through shell; symlinks/junctions (lexical path, not `realpath`); fail-open (a broken guard never breaks the session, an unreadable session falls back to the setup directory); `eval/` is a source root and `reports/` is a reserved artifact root only inside the location (project code does not go there). A tool denial is a role rule, not a failure: delegate the edit to a subagent.
 - Several `fix-runner` instances may run in parallel (background) — only in **separate workspaces**, and only when their **file sets** cannot overlap: each with its own git worktree **outside the project tree** and its own branch (`git worktree add -b fix/<round>-<n> <path> <base>`; `worktree_create` — only with an immediate `git switch -c fix/<round>-<n>`), the "to close" lists and the file sets do not overlap (the root counts the overlap of the sets before launching: an overlap ⇒ serialization or splitting the paths). Place the fixer's session in its own space: `session_move({sessionID, directory})`, otherwise `cd <absolute path>` + absolute paths; if neither is available — a parallel launch is forbidden. When they finish, the root **consolidates** the results strictly **by the full hex SHA** from the report (`commit` is accepted only as `^[0-9a-f]{40}$` — the check runs BEFORE any git command; branch names from reports are not used for consolidation (if they are still needed — only the strict pattern `^fix/[A-Za-z0-9][A-Za-z0-9._-]*$` + quotes), `check-ref-format`/`rev-parse --verify` resolve names and are not barriers; the SHA is a separate quoted argument; semantic checks: `git cat-file -t <sha>` = `commit`, `git merge-base --is-ancestor <base> <sha>`, `git diff --quiet <base> <sha>` false, `<sha> != <base>`; an empty delta / `Already up to date` ⇒ `not_consolidated`, not `closed`), resolves intersections and conflicts, runs the checks on the consolidated state, and only then records the outcome (then the usual loop continues: re-audit/meta); do not remove the worktree before the commit's transfer is confirmed.
-- Parallel background tasks: read-only roles — freely; parallel `fix-runner` — only per the isolated-workspaces rule (above); meanwhile the root does not write to the files the fixers are editing. In the audit mode the writers are only the root and `fix-runner`; `general` — only large tasks outside the audit mode.
+- Parallel background tasks: read-only roles — freely; parallel `fix-runner` — only per the isolated-workspaces rule (above); meanwhile the root does not write to the files the fixers are editing. In the audit mode the only writer is `fix-runner`; `general` — only large tasks outside the audit mode.
 - In the audit mode you do not audit yourself and do not substitute for the auditors' verdicts; disputed matters — only `arbiter`.
-- In the audit mode — do not fix before the verdict: fixes (root or `fix-runner`) start only after the summary's verdict is recorded, and for MAJOR — after independent verification/arbitration.
+- In the audit mode — do not fix before the verdict: fixes (`fix-runner`) start only after the summary's verdict is recorded, and for MAJOR — after independent verification/arbitration.
 - The subagents are universal; project specifics — only in the task.
 - Do not poll; if interrupted — continue the same session.
 - "Owner" = the user. Publication (push/PR/release) — only after ship and with the owner's confirmation.