opencode-orchestrator-uni 0.3.1 → 0.5.0

package/README.md

@@ -8,13 +8,18 @@ ships the **orchestrator agent kit**:
 - `orchestrator` — the root orchestrator (primary agent) with the audit loop as a
   built-in mode;
 - read-only audit subagents — `factcheck`, `empiric`, `invariant`,
-  `arbiter`, `meta`, `redteam`;
+  `arbiter`, `meta`, `redteam`, `context-lint`;
 - `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`);
-- three deterministic, read-only tools — `orch_uni_validate_report`, `orch_uni_snapshot`,
-  `orch_uni_sessions` (see [Tools](#tools)).
+  `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).
 
 The package is loaded directly from TypeScript: `exports` points at
 [`index.ts`](./index.ts). There is **no build step and no `dist/`** — OpenCode's
@@ -34,31 +39,49 @@ On setup (`ctx.agent.transform` / `ctx.reference.transform`):
 | `arbiter`   | `subagent` | Read-only: resolves disputed findings only               |
 | `meta`      | `subagent` | Read-only: meta-audit of reports (pass/fail gate)        |
 | `redteam`   | `subagent` | Read-only: acceptance red team (release gates)           |
+| `context-lint` | `subagent` | Read-only: audits AGENTS.md/SPEC.md for token efficiency |
 | `fix-runner`      | `subagent` | Writer: applies the fix list and proves closure          |
 
 All agents ship **without a model**: models are deployment configuration (see
 [Models](#models)). Definitions live in [`agents/`](./agents) as plain Markdown agent
 files and are parsed at setup time — the files are the single source of truth.
 
+"Read-only" here means `edit` is denied and the prompt forbids writes; `shell` stays
+allowed so an auditor can run the verification commands it needs (accepted risk
+I-M15). The audit loop treats that as a contract, not as a sandbox.
+
 The `audit-kit` reference points at this package's per-locale `docs/<locale>/`
 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 three deterministic, **read-only** tools in the `orch_uni`
-namespace — see [Tools](#tools).
+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
+
+| Command | What it does |
+| --- | --- |
+| `/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.
 
 ## Tools
 
 | Effective name           | Read-only | What it does                                                                  |
 | ------------------------ | --------- | ----------------------------------------------------------------------------- |
 | `orch_uni_validate_report`  | yes       | Extract the SGR JSON block of a report, resolve its schema, validate it        |
+| `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 three 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`
@@ -98,12 +121,90 @@ invariant that is `violated` without a counterexample, an uncovered mandatory
 `lines_checked` line, `meta`'s `verdict` diverging from its `gate`, and
 `redteam`'s `closing_list`/`verdict` invariants.
 
-The seven schemas ship as `schemas/*.json` and are derived **strictly** from the SGR
+The schemas ship as `schemas/*.json` and are derived **strictly** from the SGR
 sections of `agents/*.md`, which stay the source of truth: the test suite parses every
 agent's SGR template and fails when a prompt field or enum value is not accepted by its
-schema. Schemas set `additionalProperties` permissively — agents may add fields of their
+schema. `context-lint-failure/v1` is the typed failure envelope of
+`orch_uni_context_lint` — it has no agent template and is never a report. Schemas set
+`additionalProperties` permissively — agents may add fields of their
 own (`verdict_label`, `check`, …).
 
+### `orch_uni_context_lint`
+
+```jsonc
+{ "path": "AGENTS.md" }                  // file or directory, relative to the location
+{ "path": ".", "max_lines": 150, "max_tokens": 2000 }
+{ "path": ".", "max_words": 2000 }       // SPEC word budget; default 1500 (target), ceiling 2000
+{ "path": ".", "max_file_bytes": 500000, "max_files": 100, "max_findings": 50, "max_total_findings": 500 }
+```
+
+Deterministic, read-only audit of `AGENTS.md`, `SPEC.md` and `CLAUDE.md`. It returns
+`{ schema: "context-lint/v1", ok: true, verdict, closing_list, files, summary, truncated? }`;
+each finding carries `id`, `severity`, `kind`, `evidence`, `detail` and `fix`. Checks:
+line/token/word budget, distinct vague phrases, duplicate lines, broken relative links,
+placeholders, dates/versions in the first three lines, required sections and AC test
+columns. Links and explicit targets are confined by their **real** path: a symlink or
+junction that resolves outside the root is skipped, and such a target is refused
+(`E_OUT_OF_ROOT`). Code fences, inline code and HTML comments are masked, so a sample is
+never a rule: structural checks (commands, boundaries, verification) read the full mask,
+while requirements, AC ids and non-goals read the fence mask. Link targets are
+streamed from the line scanner one at a time (no candidate array), so memory does
+not grow with the number of links; checks are capped per file at 50 000
+candidates, the signal is checked per line and every 100 candidates, and the
+link caches keep at most 5 000 entries, so an abort wins; 2001 links are checked
+normally, 50 000 valid links still pass, and the 50 001st candidate makes the list
+incomplete (`truncated: true` plus a MAJOR `link candidates truncated` marker in
+`closing_list`), so a capped run can never pass. Broken
+links have no separate per-file cap: the finding caps bound the output and report the
+overflow. A line is scanned however long it is: the link scanner and the placeholder regex
+are linear, so a 4100-character line is checked like any other and a broken link or
+placeholder on it is the real finding, not a marker. Duplicate lines have no inner cap.
+UNC/network targets are never probed. Measured (bun 1.4.2, Windows, fresh
+process): 50 001 broken links with `max_findings: 2` → ~1.4 s and ~67 MB peak
+RSS; 50k plain lines → ~0.14 s / ~65 MB; a 2 MB single line with links →
+~3.1 s / ~116 MB (~41 MB without links). Masking reuses a line as-is when it
+has no backtick and no `<pre>`/`<code>`/`<!--`, so it never copies a line
+character by character, and a 2 MB single line stays capped at 50 000
+candidates instead of materializing every link.
+Limits: ≤ 2 MB per file, ≤ 500 files per scan. `max_findings` (per file) is N per
+severity: up to N MAJOR and N MINOR/INFO are kept, and any excess is replaced by one
+marker (MAJOR when a MAJOR was dropped, otherwise INFO); a MAJOR marker stays in
+`closing_list`. `max_total_findings` (global, default 1000) keeps MAJOR
+findings first; when MAJOR overflow, `max_total` findings plus one MAJOR `truncated`
+marker are kept. A capped list sets `truncated: true` instead of hiding findings.
+Markers are additional to `max_findings` and do not consume its budget: a capped
+link-candidate list and a capped findings list report one marker each in the same run, so
+`max_findings: 2` over 20 001 broken links yields 2 kept findings plus 2 markers. Cap
+markers point at `file:1` in `evidence`.
+Non-goals are counted as top-level items: a wrapped paragraph is one item, inline
+`;`/`,`/`and`/`и` split only at the top level (not inside `(…)`, `[…]`, backticks of any
+width or `<code>`), and a bullet at 0–4 spaces under the label is an item — fenced,
+`<pre>` and deeper-indented code is not.
+Placeholders are `<...>` (three or more dots) and `TODO`/`TBD`/`FIXME`; `<DoD>` and
+`<name>` are markup.
+`max_lines` is the single 200-line root budget the tool applies: the 60/200/100
+per-level figures in [`docs/`](./docs) are authoring guidance, not separate tool limits.
+`max_words` defaults to the 1500-word SPEC target; pass `max_words: 2000` to enforce the
+documented ceiling instead.
+Typed failures: `E_INPUT`, `E_NOT_FOUND`, `E_NO_FILES`, `E_IO`, `E_ABORTED`,
+`E_LIMIT_FILE`, `E_LIMIT_FILES`, `E_OUT_OF_ROOT`.
+A failure is a typed payload `{schema:"context-lint-failure/v1", ok:false, code, message, path?, bytes?, files?, max?}`
+that validates only against `context-lint-failure/v1`; a report is
+`{schema:"context-lint/v1", ok, verdict, closing_list, files, summary, truncated?}` and every file carries `lines`,
+`words`, `chars` and `tokens_est` (tokens are estimated as Cyrillic/3 + the rest/4). A directory
+target is scanned to depth 3, and `max_files` refuses early: the walk stops at the first file above
+the limit. Nothing is dropped silently: a directory below the depth limit, a link or junction that
+resolves outside the workspace root, and an unclosed fence, `<pre>` or HTML comment are INFO
+findings, so a `pass` never hides an unchecked region. An unclosed `<code>` is a
+line-local mask: it hides the rest of its line and is not reported (only fence,
+`<pre>` and HTML comments span lines and get an INFO marker). An abort is observed
+between files, every 2048 lines of a line-oriented check and at each gate, so the
+worst-case latency is one mask pass over a file capped by `max_file_bytes` (tens of
+milliseconds per 2 MB), not the whole scan. Commands count only inside code, a Task table
+or a Commands section, an HTML comment such as `<!-- npm install -->` is not a command, and `make`
+needs a target, so prose such as "Make sure …" is not a command. A scan started at the root also
+picks up fixture trees such as `eval/`; pass an explicit path for the canonical files.
+
 ### `orch_uni_snapshot`
 
 ```jsonc
@@ -162,6 +263,134 @@ own (`verdict_label`, `check`, …).
 `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
@@ -309,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 (93 tests in 8 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

@@ -8,13 +8,18 @@
 - `orchestrator` — root-оркестратор (основной агент) со встроенным режимом
   аудиторского цикла;
 - read-only субагенты аудита — `factcheck`, `empiric`, `invariant`,
-  `arbiter`, `meta`, `redteam`;
+  `arbiter`, `meta`, `redteam`, `context-lint`;
 - `fix-runner` — единственный пишущий субагент (применяет список «к закрытию»);
 - процессные документы комплекта, доступные как **reference `audit-kit`**
   (`call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`,
-  `instruction-other-session.md`);
-- три детерминированных read-only инструмента — `orch_uni_validate_report`,
-  `orch_uni_snapshot`, `orch_uni_sessions` (см. [Инструменты](#инструменты)).
+  `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-разрешение
+остаётся, чтобы запускать проверки (принятый риск, ни одно разрешение не ослаблено).
 
 Пакет загружается напрямую из TypeScript: `exports` указывает на
 [`index.ts`](./index.ts). **Шага сборки и каталога `dist/` нет** — Bun-овый
@@ -34,6 +39,7 @@
 | `arbiter`      | `subagent` | Read-only: разбирает только спорные находки                      |
 | `meta`         | `subagent` | Read-only: мета-аудит отчётов (гейт pass/fail)                   |
 | `redteam`      | `subagent` | Read-only: приёмочный ред-тим (релизные ворота)                  |
+| `context-lint` | `subagent` | Read-only: аудит AGENTS.md/SPEC.md на token-эффективность         |
 | `fix-runner`   | `subagent` | Пишущий: применяет список правок и доказывает закрытие           |
 
 Все агенты поставляются **без модели**: модели — это конфигурация развёртывания
@@ -41,26 +47,45 @@
 Markdown-файлы агентов и парсятся при setup — файлы являются единственным
 источником истины.
 
+«Read-only» здесь означает: `edit` запрещён и промпт запрещает запись; `shell`
+остаётся разрешён, чтобы аудитор мог выполнить нужные проверки (принятый риск
+I-M15). Аудиторский цикл считает это контрактом, а не песочницей.
+
 Reference `audit-kit` указывает на per-locale каталог `docs/<locale>/` пакета
 (см. [Локаль](#локаль)). OpenCode перечисляет его в контексте сессии как
 дополнительный локальный каталог, поэтому оркестратор (и любой другой агент)
 может читать процессные документы напрямую, например
 `<reference path>/call-mechanics.md`.
 
-Плагин также регистрирует три детерминированных **read-only** инструмента в
-пространстве имён `orch_uni` — см. [Инструменты](#инструменты).
+Плагин также регистрирует пять детерминированных **read-only** инструментов в
+пространстве имён `orch_uni` и три слэш-команды — см. [Инструменты](#инструменты)
+и [Команды](#команды).
+
+## Команды
+
+| Команда | Что делает |
+| --- | --- |
+| `/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 и
+подтверждения.
 
 ## Инструменты
 
 | Имя                        | Read-only | Что делает                                                                    |
 | -------------------------- | --------- | ----------------------------------------------------------------------------- |
 | `orch_uni_validate_report` | да        | Достаёт SGR JSON-блок отчёта, разрешает его схему, валидирует                 |
+| `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`
@@ -99,12 +124,87 @@ claim'а `empiric` с `method` = `run|measure|compare_base`, элементы `s
 непокрытая обязательная строка `lines_checked`, расхождение `verdict` и `gate` у
 `meta`, инварианты `closing_list`/`verdict` у `redteam`.
 
-Семь схем лежат в `schemas/*.json` и выведены **строго** из SGR-секций
+Схемы лежат в `schemas/*.json` и выведены **строго** из SGR-секций
 `agents/*.md`, которые остаются источником истины: тестовый набор парсит
 SGR-шаблон каждого агента и падает, когда поле промпта или значение enum не
-принимается его схемой. Схемы разрешают `additionalProperties` — агенты могут
+принимается его схемой. `context-lint-failure/v1` — типизированный конверт ошибки
+`orch_uni_context_lint`: у него нет шаблона агента, и отчётом он не является. Схемы
+разрешают `additionalProperties` — агенты могут
 добавлять свои поля (`verdict_label`, `check`, …).
 
+### `orch_uni_context_lint`
+
+```jsonc
+{ "path": "AGENTS.md" }                  // файл или каталог, относительно локации
+{ "path": ".", "max_lines": 150, "max_tokens": 2000 }
+{ "path": ".", "max_words": 2000 }       // бюджет слов SPEC; по умолчанию 1500 (цель), потолок 2000
+{ "path": ".", "max_file_bytes": 500000, "max_files": 100, "max_findings": 50, "max_total_findings": 500 }
+```
+
+Детерминированный read-only аудит `AGENTS.md`, `SPEC.md` и `CLAUDE.md`. Возвращает
+`{ schema: "context-lint/v1", ok: true, verdict, closing_list, files, summary, truncated? }`;
+каждая находка несёт `id`, `severity`, `kind`, `evidence`, `detail` и `fix`. Проверки:
+бюджет строк/токенов/слов, различные vague-фразы, дубли строк, битые относительные ссылки,
+плейсхолдеры, даты/версии в первых трёх строках, обязательные секции и колонка Test
+у AC. Ссылки и явные цели ограничены **реальным** путём: symlink/junction, ведущий за
+пределы корня, пропускается, а такая цель отклоняется (`E_OUT_OF_ROOT`). Код-фенсы,
+inline-код и HTML-комментарии маскируются: пример не считается правилом — структурные
+проверки (команды, границы, проверка) читают полную маску, а требования, AC-id и
+non-goals — маску фенсов. Цели ссылок передаются из построчного сканера по одной
+(массива кандидатов нет), поэтому память не растёт с числом ссылок; проверки ограничены
+на файл 50 000 кандидатами, сигнал проверяется на каждой строке и каждые 100 кандидатов,
+а кэши ссылок держат не более 5 000 записей, поэтому abort срабатывает; 2001 ссылка
+проверяется обычным образом, 50 000 валидных ссылок дают pass, а 50 001-й кандидат делает
+список неполным (`truncated: true` плюс MAJOR-маркер `link candidates truncated` в
+`closing_list`), он не может дать pass.
+Отдельного потолка на
+битые ссылки нет: вывод ограничивают общие лимиты находок, а переполнение помечается.
+Строка сканируется любой длины: сканер ссылок и регулярное выражение плейсхолдеров линейны,
+поэтому 4100-символьная строка проверяется как любая другая, а битая ссылка или
+плейсхолдер на ней — настоящая находка, а не маркер. Внутреннего потолка дублей нет. Цели
+UNC/сетевые пути никогда не пробуются. Замер (bun 1.4.2, Windows, свежий процесс):
+50 001 битая ссылка с `max_findings: 2` → ~1,4 с и ~67 МБ пикового RSS; 50 тыс.
+обычных строк → ~0,14 с / ~65 МБ; одна строка 2 МБ со ссылками → ~3,1 с / ~116 МБ
+(~41 МБ без ссылок). Маскирование переиспользует строку как есть, если в ней нет
+backtick и `<pre>`/`<code>`/`<!--`, поэтому не копирует строку посимвольно, а строка
+в 2 МБ остаётся ограниченной 50 000 кандидатами, а не материализует все ссылки.
+Лимиты: ≤ 2 МБ на файл, ≤ 500 файлов за прогон. `max_findings` (на файл) — это N на
+severity: сохраняются до N MAJOR и N MINOR/INFO, излишек заменяется одним маркером
+(MAJOR, если выпал MAJOR, иначе INFO); MAJOR-маркер остаётся в `closing_list`.
+`max_total_findings` (глобально, по умолчанию 1000)
+сохраняет сначала MAJOR; при переполнении MAJOR остаются `max_total` находок плюс один
+MAJOR-маркер `truncated`. Усечённый список помечается `truncated: true`, а не скрывается.
+Маркеры дополнительны к `max_findings` и не расходуют его бюджет: маркер усечённых
+кандидатов-ссылок и маркер усечённых находок дают по маркеру в одном прогоне, поэтому
+`max_findings: 2` на 20 001 битой ссылке даёт 2 сохранённые находки плюс 2 маркера. Маркеры
+указывают на `file:1` в `evidence`.
+Non-goals считаются как элементы верхнего уровня: перенесённый абзац — один элемент,
+inline `;`/`,`/`and`/`и` делят только верхний уровень (не внутри `(…)`, `[…]`, бэктиков
+любой длины или `<code>`), а bullet с отступом 0–4 пробела под лейблом — элемент; фенсы,
+`<pre>` и код с большим отступом — нет.
+Плейсхолдеры — `<...>` (три и более точки) и `TODO`/`TBD`/`FIXME`; `<DoD>` и `<name>` —
+разметка.
+`max_lines` — единственный бюджет корня (200 строк), который применяет инструмент;
+цифры 60/200/100 по уровням в [`docs/`](./docs) — ориентир для авторов, а не отдельные
+лимиты инструмента. `max_words` по умолчанию равен цели 1500 слов SPEC; передайте
+`max_words: 2000`, чтобы применять документированный потолок. Типизированные ошибки: `E_INPUT`, `E_NOT_FOUND`, `E_NO_FILES`,
+`E_IO`, `E_ABORTED`, `E_LIMIT_FILE`, `E_LIMIT_FILES`, `E_OUT_OF_ROOT`.
+Ошибка — типизированный payload `{schema:"context-lint-failure/v1", ok:false, code, message, path?, bytes?, files?, max?}`,
+который валидируется только по `context-lint-failure/v1`; отчёт —
+`{schema:"context-lint/v1", ok, verdict, closing_list, files, summary, truncated?}`, и каждый файл несёт `lines`,
+`words`, `chars` и `tokens_est` (токены оцениваются как кириллица/3 + прочее/4). Каталог
+сканируется до глубины 3, а `max_files` отказывает рано: обход останавливается на первом файле
+выше лимита. Ничего не пропадает молча: каталог ниже лимита глубины, ссылка или junction вне
+корня workspace и незакрытые fence, `<pre>` или HTML-комментарий дают INFO-находки, поэтому `pass`
+не скрывает непроверенную область. Незакрытый `<code>` — строчная маска: он скрывает
+остаток своей строки и не репортится (INFO дают только fence, `<pre>` и HTML-комментарий,
+которые тянутся через строки). Отмена наблюдается между файлами, каждые 2048 строк
+построчной проверки и в каждом гейте, поэтому худшая латентность — один проход маски по
+файлу под `max_file_bytes` (десятки мс на 2 МБ), а не весь скан. Команды считаются только в коде, таблице задач или секции
+Commands, HTML-комментарий вроде `<!-- npm install -->` командой не является, а `make` требует
+цели, поэтому проза «Make sure …» — не команда. Скан от корня подхватывает и фикстуры вроде
+`eval/`; передайте явный путь, если нужны только канонические файлы.
+
 ### `orch_uni_snapshot`
 
 ```jsonc
@@ -165,6 +265,136 @@ SGR-шаблон каждого агента и падает, когда пол
 `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`; модели настраиваются у записи плагина в
@@ -316,7 +546,7 @@ npm run lint:fix     # biome check --write . (применяет безопас
 
 Команды `check:locales` и `verify:kit` требуют git-чекаута комплекта — в npm-пакете каталог `tools/` не поставляется, поэтому в установленном пакете они недоступны (`stand: unavailable` и собственные воспроизводимые проверки).
 
-`npm test` сканирует только `./test/` — поставляемый набор (93 теста в 8 файлах;
+`npm test` сканирует только `./test/` — поставляемый набор (400 тестов в 10 файлах;
 до стражей идентификаторов было 72 в 5). Голый `bun test` из корня репозитория
 красный по замыслу: позиционный аргумент `bun test` — это фильтр-подстрока пути,
 поэтому голая команда подхватывает и специально падающие фикстуры в