opencode-orchestrator-uni 0.3.1 → 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/context-efficiency.md

@@ -0,0 +1,196 @@
+# Token-efficient AGENTS.md и SPEC.md
+
+Файл инструкций — это бюджет внимания, а не документация. Оплачивается каждая строка: она участвует в контексте каждой сессии и конкурирует с задачей. Цель — минимум проверяемых правил, которые нельзя вывести из кода и которые нужны в большинстве сессий.
+
+## Бюджет
+
+| Файл | Цель | Потолок |
+|---|---:|---:|
+| Глобальный `AGENTS.md` | 25–40 строк / <500 токенов | 60 строк |
+| Корневой `AGENTS.md` | 100–200 строк / 1–2k токенов | 200 строк |
+| Вложенный `AGENTS.md` | 20–60 строк / <700 токенов | 100 строк |
+| `SPEC.md` | 80–150 строк / ≤1,5k слов | 2k слов |
+| `ADR` | 30–60 строк / <700 токенов | 100 строк |
+
+`orch_uni_context_lint` применяет один бюджет корня (`max_lines`, по умолчанию 200 строк) и бюджет слов SPEC (`max_words`, по умолчанию 1500 — цель из таблицы; потолок 2k включается через `max_words: 2000`). Цифры по уровням выше — ориентир для автора, а не отдельные лимиты инструмента. Инструмент сообщает о том, что не проверял (ссылки вне корня, каталоги глубже глубины 3, незакрытый фенс), INFO-находками, поэтому `pass` никогда не означает «непроверено».
+
+Правило отбора: если строка не проверяема, выводима из кода/линтера или нужна реже половины сессий — удалить либо вынести в ссылку.
+
+## AGENTS.md: 12 правил
+
+1. Команды — в начало: install, build, test, one test, lint, run; с флагами и рабочей директорией.
+2. Только невыводимое: флаги, ловушки, порядок слоёв, запреты, версии.
+3. Одна инструкция — одна строка, императив, проверяемо.
+4. Стиль — линтеру; не пересказывать README и стандарт языка.
+5. Явные «Never» и «Ask first»: секреты, `dist/`, prod, миграции, зависимости.
+6. Приоритеты — в тексте: что переопределяет что; при конфликте — остановись и спроси.
+7. Один источник правды: `AGENTS.md` + симлинк/импорт для `CLAUDE.md`.
+8. Ссылки вместо инлайна; инлайнить только то, что нужно всегда.
+9. Правило добавлять после повторной ошибки агента, а не «на будущее».
+10. Мёртвое правило удалять: это налог на каждый запрос.
+11. Стабильное — вверх, даты/ветки/задачи — вниз (prefix cache).
+12. Ревьюить файл как код; менять при смене тулинга/CI.
+
+## Шаблон AGENTS.md
+
+```md
+# AGENTS.md
+
+## Приоритеты
+1. Явное указание пользователя в задаче.
+2. SPEC.md активной фичи.
+3. Ближайший AGENTS.md.
+4. Этот файл.
+5. Глобальный AGENTS.md.
+При конфликте — остановись и спроси.
+
+## Команды
+| Задача | Команда | Примечание |
+|---|---|---|
+| Установка | `<...>` | `<версия>` |
+| Сборка | `<...>` | `<флаг>` |
+| Тесты | `<...>` | `<лимит>` |
+| Один тест | `<...>` | `<имя>` |
+| Линт/типы | `<...>` | |
+| Запуск | `<...>` | `<порт>` |
+
+## Границы
+- `<path>/` — сгенерировано, не редактировать.
+- `<path>/` — вендорное, не редактировать.
+- Новые файлы — в `<path>`.
+
+## Конвенции
+- <Одно проверяемое правило на строку.>
+
+## Проверка
+`<analyze>` → `<lint>` → `<test>`.
+Готово = все команды зелёные + `<DoD>`.
+
+## Никогда / сначала спроси
+- Никогда: секреты, `dist/`, prod, применённые миграции.
+- Сначала спроси: схема БД, публичный API, новые зависимости, CI.
+
+## Указатели
+- `SPEC.md` — контракт фичи.
+- `docs/adr/` — решения.
+- `docs/pitfalls.md` — ловушки.
+```
+
+## SPEC.md: 12 правил
+
+1. Одна фича — один файл, 1–3 страницы; больше — split через roadmap.
+2. Стабильные ID (`R1`, `AC1.1`), не перенумеровывать.
+3. Одно требование — одно наблюдаемое поведение.
+4. EARS или Given/When/Then — единообразно; MUST/SHOULD/MAY — редко.
+5. Никакого HOW: стек, файлы, классы — в plan/design/ADR.
+6. Контракты — ссылками, не копиями.
+7. Non-goals — 3–7 пунктов.
+8. Инварианты — отдельно от acceptance criteria.
+9. Таблицы — для AC и трассировки; проза — для контекста.
+10. Frontmatter: `status`, `owner`, `version`, `supersedes`; без changelog в теле.
+11. Не более трёх открытых вопросов, у каждого owner и дата; `TBD` в других местах запрещён.
+12. DoD и метрики — измеримые; «быстрее» без числа не считается.
+
+## Шаблон SPEC.md
+
+```md
+---
+id: SPEC-000
+title: <название>
+status: draft
+owner: "@team"
+version: 1.0.0
+supersedes: —
+---
+
+# SPEC-000: <название>
+
+## 1. Контекст и проблема
+<3–5 строк: кто страдает, в чём боль, почему сейчас.>
+
+## 2. Цель и non-goals
+**Цель:** <одно предложение>.
+**Non-goals:** <3–7 пунктов «сознательно не делаем»>.
+<!-- один пункт на строку с `-` и отступом 0–4; перенесённый абзац — один пункт;
+     фенс, `<pre>` и bullet с отступом 5+ — код, не пункт. -->
+
+## 3. Сценарии
+| ID | Роль | Цель | Ценность | Независимый тест |
+|---|---|---|---|---|
+| S1 | <...> | <...> | <...> | <...> |
+
+## 4. Требования (EARS)
+- **R1** — WHEN <триггер>, THE SYSTEM SHALL <результат>.
+- **R2** — IF <условие>, THEN THE SYSTEM SHALL <...>.
+
+## 5. Acceptance criteria
+| AC | R | Given | When | Then | Test |
+|---|---|---|---|---|---|
+| AC1.1 | R1 | <...> | <...> | <...> | `test_...` |
+
+## 6. Инварианты и краевые случаи
+- Инвариант: <всегда истинно>.
+- Пусто/лимит/конкурентность/ошибка: <...>.
+
+## 7. Контракты
+Ссылки: `<openapi.yaml>`, `<schema.sql>`, `<types.ts>`.
+
+## 8. Нефункциональные требования
+| Метрика | Цель | Как проверяем |
+|---|---|---|
+| Latency p95 | <...> | <...> |
+
+## 9. Метрики успеха
+- **SC-1** — <число и способ проверки>.
+
+## 10. Открытые вопросы
+- **Q1** — <...>; owner: <...>; до <дата>.
+
+## 11. Трассировка
+| R | AC | Task | Test |
+|---|---|---|---|
+| R1 | AC1.1 | T1 | `test_...` |
+
+## 12. Definition of Done
+- [ ] AC закрыты.
+- [ ] Тесты зелёные.
+- [ ] Контракты и docs/ADR обновлены.
+```
+
+## Команда /agents-md
+
+1. Определи режим: аудит существующего файла или черновик с нуля.
+2. Для аудита: `orch_uni_context_lint` → `context-lint`; покажи SGR и `closing_list`.
+3. Для черновика: собери факты и задай не более 8 вопросов; не выдумывай команды и пути.
+4. Заполни шаблон; уложись в 150–200 строк.
+5. Прогони линтер, покажи diff и открытые вопросы.
+6. Канонический файл меняй только после подтверждения; правки — через `fix-runner`.
+
+## Команда /spec
+
+1. Зафиксируй бриф и задай не более 5 уточняющих вопросов.
+2. Non-goals, приоритеты и метрики утверждает владелец; не придумывай их.
+3. Заполни шаблон: EARS, AC с тестами, инварианты, трассировка, DoD.
+4. Прогони `orch_uni_context_lint` и `context-lint`; покажи diff и вопросы.
+5. Канонический файл меняй только после подтверждения.
+
+## Ревью
+
+- [ ] `AGENTS.md` ≤200 строк, `SPEC.md` ≤1,5k слов.
+- [ ] Каждая строка проверяема.
+- [ ] Нет дублей с README/линтером/CI.
+- [ ] Приоритеты и границы прописаны.
+- [ ] Все относительные ссылки существуют.
+- [ ] У каждого R есть AC, у каждого AC есть тест.
+- [ ] Non-goals и DoD на месте.
+- [ ] Есть baseline на 10–20 задачах.
+
+## Анти-паттерны
+
+| Анти-паттерн | Почему плохо | Что делать |
+|---|---|---|
+| Автогенерация «на всякий случай» | −0,5…−2% успеха, +20–23% косты | Писать вручную, только высокосигнальное |
+| Пересказ README/архитектуры | Дублирование, нулевой эффект | Ссылка на docs |
+| Дублирование линтера | Токены на то, что и так проверяется | Линтер/CI |
+| Общие фразы («пиши чисто») | Непроверяемо | Императив + пример |
+| Противоречия между уровнями | Модель выбирает произвольно | Явные приоритеты |

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, а не с пересказа.