devcontour-harness 0.1.0-alpha.5 → 0.1.0-alpha.7

package/docs/review-probes.md

@@ -0,0 +1,199 @@
+# Проверки reviewer (`run_check`) и объявленные gates
+
+Reviewer кода, которому профиль разрешает запускать команды, получает MCP-инструмент
+`devcontour_probe.run_check`. Его исполняет controller: песочница ОС, исходники только для
+чтения, предел на команду, общий бюджет проверок и резерв времени на заключение.
+
+## Два вида вызова
+
+| Вызов                           | Что исполняется                                                                | Куда можно писать                           |
+| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
+| `{"argv": ["node", "-e", "…"]}` | исследовательская команда reviewer, без shell, в корне проверяемого дерева     | только собственный `TMPDIR`                 |
+| `{"gate": "domain"}`            | объявленный gate из эффективной политики: его `command`, `cwd`, окружение фазы | только scratch отчёта controller и `TMPDIR` |
+
+Других полей нет: `env`, `cwd`, `reportPath`, `write`, `scope` и любые неизвестные поля —
+ошибка протокола (`-32602`), ничего не запускается. Можно передать `timeoutMs`, но он только
+уменьшает предел controller. Неизвестный ID и генеративный gate (`property`) — результат
+`rejected`, бюджет не тратится.
+
+Запрос reviewer содержит готовый вызов для каждого объявленного gate, например:
+
+```text
+To run a declared gate, call run_check with exactly {"gate":"domain"}, {"gate":"api"} (one gate per call).
+```
+
+## Что делает controller при `{"gate": "<id>"}`
+
+1. Берёт gate из спецификации probe (копия gates поручения из эффективной политики).
+2. Проверяет `cwd`: реальный путь внутри проверяемого дерева, иначе `rejected`.
+3. Если путь отчёта зашит в argv (см. ниже) — не запускает, возвращает ошибку среды с рецептом.
+4. Создаёт каталог evidence `<каталог ревью>/probe-runs/<runId>/` (вне дерева, без перезаписи) и
+   уникальный scratch `dc-probe-report-*` во временном каталоге системы.
+5. Выставляет `HARNESS_REPORT_PATH` и `DEVCONTOUR_REPORT_PATH` = `<scratch>/<id>.xml`, `CI=1`;
+   у `test` gate ещё `TURBO_FORCE=true` и `GOFLAGS=… -count=1`, как у gate движка.
+6. Запускает команду в песочнице: запись — только в scratch и `TMPDIR`; дерево, `.git`,
+   каталог controller и прежние `.reports/*.xml` закрыты на запись.
+7. Читает отчёт: symlink, жёсткая ссылка, путь вне scratch — `unsafe` (не читается); файл старше
+   запуска — `stale`; не JUnit или без testcases — `corrupt`; нет файла — `missing`.
+8. Сохраняет замаскированную копию отчёта (`<id>.xml`), журнал (`<id>.log`) и `run.json`, затем
+   удаляет scratch. Таймаут и отмена (`notifications/cancelled`) останавливают процессы проверки,
+   evidence сохраняется тоже.
+
+Результат и запись в `probes.jsonl` содержат `runId`, `status`, фактический `argv`, `gate.id`,
+`gate.phase`, `gate.sha`, `gate.cwd`, `gate.controllerEnv` (только имена), `gate.report`
+(`status`, `path`, `digest` — SHA-256 сохранённых байтов, `tests`, `failures`, `skipped`),
+`gate.scratchRemoved` и `log` — журнал controller. `review.json` переносит эти записи в
+`probes`; `reproduction.run` находки ссылается на `runId`, а через него — на журнал.
+
+## Бюджет проверок и авария controller
+
+Бюджет проверок общий на логическое ревью (область, фаза, SHA), включая повторы reviewer и
+рестарт controller. Учёт — журнал `probes.jsonl` каждого вызова:
+
+1. До запуска команды controller резервирует её предел и синхронно пишет строку
+   `{"type":"start","runId","reservedMs","startedAt","pid"}` с fsync. Не удалось записать —
+   `error`/`environment`, команда не запускается.
+2. Команда и все её потомки получают `HARNESS_PROBE_RUN=<runId>`.
+3. Строка исхода (обычная запись запуска) разрешает резерв фактической длительностью.
+4. Новый controller перед следующим вызовом reviewer считает расход: завершённые — по
+   длительности, начатые без исхода — **весь резерв** (время до гибели не известно точно и не
+   больше резерва; засчитывается верхняя граница). Пережившие процессы такого запуска (по метке
+   и их группам процессов) останавливаются, в журнал дописывается
+   `{"type":"abandoned","runId","chargedMs"}`; повторное восстановление расход не меняет, а
+   строка исхода, пришедшая позже, заменяет списание фактом без двойного счёта.
+5. Следующий вызов получает бюджет `budget − spent` и прежний срок логического ревью; остаток
+   меньше секунды — вызов без инструмента проверок.
+
+Ограничение: на macOS `ps -E` не показывает окружение системных бинарников (например,
+`/bin/sleep`); такой процесс останавливается, если он в группе процессов запуска.
+
+## Статусы
+
+| `status`                       | `failure`     | Смысл                                                                                                                                   |
+| ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `passed`                       | —             | код 0 и (для gate с отчётом) свежий JUnit без failures и skips                                                                          |
+| `failed`                       | —             | код ≠ 0 или упали testcases: наблюдение о коде                                                                                          |
+| `failed`                       | `report`      | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде                                                |
+| `error`                        | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет песочницы |
+| `timeout`, `cancelled`         | —             | команда остановлена вместе с потомками                                                                                                  |
+| `budget-exhausted`, `rejected` | —             | команда не запускалась                                                                                                                  |
+
+Ошибка среды и ошибка отчёта — не находка в коде; находка, сославшаяся на запуск с
+`failure: environment`, не получает `observed`.
+
+**Probe — наблюдение reviewer.** Обязательные gates candidate и integration запускает и
+оценивает движок; probe не записывает evidence gate, не ставит технический PASS и не двигает
+target ref.
+
+## Итог `inspection`: что reviewer действительно выполнил
+
+`review.json.inspection` и `EvidenceRecord.inspection` ревью кода — один и тот же объект. Его
+собирает controller для **одного вызова reviewer** из двух наблюдений: событий runtime этого
+вызова (Codex `item.completed`/`command_execution`) и журнала проверок `probes.jsonl` этого
+вызова. Самоотчёт модели (`execution.commands`, `reproduction.executed`, runId в тексте) ничего
+не подтверждает.
+
+- `mode: commands` — подтверждена хотя бы одна выполненная команда; `reason: null`. Ненулевой
+  код, таймаут или отмена после старта и ошибка среды после старта выполнение не отменяют.
+- `mode: diff-only` — подтверждённых выполнений нет; `commands: []`, `reason` объясняет.
+- `commands` — не PASS: тесты могли упасть, gates и вердикт оценивает движок. Принятие по-прежнему
+  зависит только от обязательных gates и валидного вердикта; `commands` не лечит невалидный ответ,
+  изменённое дерево или проваленный gate, а неуспешный probe сам не создаёт находку.
+
+### Граница старта
+
+Запуск probe засчитывается по признаку `started` из `runCheck`: без песочницы — процесс порождён
+(событие `spawn`), в песочнице — обёртка создала метку старта перед `exec` (запуск самой обёртки
+не считается). Признак отмечается на границе и переживает исключение после неё.
+
+| Событие                                                                                   | В `commands` |
+| ----------------------------------------------------------------------------------------- | ------------ |
+| Команда завершилась с любым кодом                                                         | да           |
+| `timeout`/`cancelled` после старта (код `null`, частичный вывод)                          | да           |
+| `error`/`environment` после старта (сеть закрыта песочницей, EPERM, сбой записи evidence) | да           |
+| `failed`/`report`: код 0, JUnit отсутствует или испорчен                                  | да           |
+| Неизвестный gate, бюджет исчерпан, нет executable, отказ песочницы или scratch до старта  | нет          |
+| Вызов отменён до запуска (`cancelled`, команда не исполнялась)                            | нет          |
+| Только резерв `start`, `abandoned`, битая строка, объект без формы исхода                 | нет          |
+
+Незасчитанные записи перечислены в `inspection.excluded` с причиной; полная диагностика — в
+`review.json.probes` и журнале.
+
+### Форма
+
+| Смысл                           | JSON path              | Тип и значения                                                                                                                                                                       |
+| ------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Источник итога                  | `source`               | `codex-events`, `unavailable` (прежние), `controller-probes`, `runtime-and-controller`                                                                                               |
+| Вызов reviewer                  | `context`              | `{attempt, phase: candidate\|integration, sha, call}`; `attempt` — ID попытки, не runId probe                                                                                        |
+| Все подтверждённые операции     | `total`                | целое ≥ 0                                                                                                                                                                            |
+| Происхождение команды           | `commands[].origins[]` | `{type: "runtime", runtime, item: string\|null}` или `{type: "controller", runId}`                                                                                                   |
+| Код выхода                      | `commands[].exitCode`  | целое или `null` (неизвестен: таймаут, отмена, старая проекция без кода)                                                                                                             |
+| Исход                           | `commands[].status`    | `completed`/`failed` (runtime); `passed`/`failed`/`timeout`/`cancelled`/`error` (probe)                                                                                              |
+| Неуспех не в коде               | `commands[].failure`   | `environment`, `report`                                                                                                                                                              |
+| Gate                            | `commands[].gate`      | ID объявленного gate                                                                                                                                                                 |
+| Пояснение controller            | `commands[].note`      | строка ≤ 2000                                                                                                                                                                        |
+| Не засчитано                    | `excluded[]`           | `{runId, status, reason}`, `reason`: `not-started`, `legacy-unconfirmed`, `foreign-scope`, `unknown-status`, `unfinished`, `abandoned`; не более 100, полное число — `excludedTotal` |
+| Строки журнала без формы исхода | `invalid`              | целое ≥ 0                                                                                                                                                                            |
+
+Пределы: не более 100 команд; `command` ≤ 12000 символов; `output` ≤ 4000 (stdout и stderr через
+перевод строки, при нехватке места — хвосты обоих примерно поровну); `note` ≤ 2000. Потоки probe
+в журнале по-прежнему ограничены хвостом 8000 с маркером `…`. Порядок: команды runtime в порядке
+потока, затем запуски probe в порядке журнала; при превышении сохраняются последние 100, а
+`mode` вычисляется по всему набору. Пользовательский текст маскируется до обрезки; перечисления и
+идентификаторы controller не маскируются.
+
+### Идентичность и область
+
+Операция одна только при надёжной идентичности: один runId probe; один item ID в потоке runtime;
+явная структурированная связь наблюдения runtime с runId probe (origin `controller` у команды
+runtime) — тогда у операции оба происхождения. Одинаковый argv с разными runId — две операции;
+совпадение текста, вывода или замаскированных аргументов не склеивает.
+
+Каждый исход в журнале несёт `scope: {attempt, phase, sha, call}`. Запись с явно чужими
+попыткой, фазой, SHA или вызовом (или gate с чужими `phase`/`sha`) не засчитывается
+(`excluded`, `foreign-scope`). `call-2` не получает команд `call-1`, integration — команд
+candidate; общий бюджет проверок логического ревью по-прежнему считается по журналам всех вызовов.
+
+### Старые записи
+
+Прежние `inspection` (без новых полей, в том числе противоречивые `diff-only` с командой) и
+evidence без `inspection` читаются как есть; чтение не пересчитывает итог, digest и решение.
+Для отдельной агрегации старых данных: завершённые события runtime засчитываются как раньше;
+записи probe без `started` со статусом `passed`/`failed` — выполнение (код и вывод, если их нет,
+остаются неизвестными: `exitCode: null`, пустой `output`); `error`/`timeout`/`cancelled` без
+подтверждения старта не засчитываются (`legacy-unconfirmed`) — это ограничение старых данных.
+Явный `started: false` главнее правила старых записей.
+
+## Рецепт: путь отчёта из переменной controller
+
+Gate пригоден для probe, если команда пишет JUnit в `HARNESS_REPORT_PATH` (или
+`DEVCONTOUR_REPORT_PATH`). Gate движка получает ту же переменную с путём `report.path` внутри
+дерева, поэтому рецепт с прежним путём по умолчанию не меняет поведение gate движка.
+
+Controller не ищет и не заменяет подстроки в argv. Если элемент argv целиком или после `=`
+(`--junitxml=…`) совпадает с `report.path` относительно `cwd` gate, probe возвращает
+`error`/`environment` с номером аргумента и рецептом, не запуская команду. Если путь зашит в
+скрипт (package script), запуск идёт, запись в дерево получает EPERM, и результат —
+та же ошибка среды с рецептом.
+
+| Инструмент                                                              | Сейчас в профилях/примерах                                                          | Пригодно для probe                                                                                                                                                                                  |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| demo runner (`test/run-tests.mjs`)                                      | читает `DEVCONTOUR_REPORT_PATH`/`HARNESS_REPORT_PATH`, иначе `.reports/<suite>.xml` | да, как есть                                                                                                                                                                                        |
+| npm (`profiles/npm-ci.json`, `examples/toolchains/npm`)                 | `npm run test` → `--test-reporter-destination=.reports/junit.xml` в package script  | `"test": "node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=${HARNESS_REPORT_PATH:-.reports/junit.xml} test/*.test.js"`         |
+| pnpm (`profiles/pnpm-frozen.json`, `examples/toolchains/pnpm`, `turbo`) | тот же путь в package script пакета                                                 | то же в script пакета; для вложенного пакета — абсолютный `HARNESS_REPORT_PATH` не зависит от каталога                                                                                              |
+| Go (`profiles/go-gotestsum.json`)                                       | `["gotestsum", "--junitfile", ".reports/junit.xml", "--", "-count=1", "./..."]`     | `["sh", "-c", "GOCACHE=\"${GOCACHE:-$TMPDIR/go-build}\" exec gotestsum --junitfile \"${HARNESS_REPORT_PATH:-.reports/junit.xml}\" -- -count=1 ./..."]`                                              |
+| Python (`profiles/python-uv.json`)                                      | `["uv", "run", "--no-sync", "pytest", "--junitxml=.reports/junit.xml"]`             | `["sh", "-c", "PYTHONDONTWRITEBYTECODE=1 UV_CACHE_DIR=\"${UV_CACHE_DIR:-$TMPDIR/uv}\" exec uv run --no-sync pytest -p no:cacheprovider --junitxml=\"${HARNESS_REPORT_PATH:-.reports/junit.xml}\""]` |
+| mixed-python (`cwd: backend`)                                           | `--junitxml=../.reports/backend.xml`                                                | `--junitxml="${HARNESS_REPORT_PATH:-../.reports/backend.xml}"` через `sh -c`                                                                                                                        |
+
+Рецепты npm, Go и Python проверены на настоящих инструментах под песочницей ОС
+<!-- repo-only -->(`tests/integration/probe-recipes.test.ts`)<!-- /repo-only -->: команда профиля даёт `error`/`environment` (для
+
+npm — после EPERM записи из package script), рецепт проходит в probe со свежим JUnit вне
+дерева и в gate движка с отчётом в дереве. Под `isolation.mode: os` cache Go и uv по умолчанию
+лежит вне доступного на запись, поэтому рецепт направляет `GOCACHE`/`UV_CACHE_DIR` в `TMPDIR`
+(если они не заданы), а pytest — без `.pytest_cache` и байткода в дереве. pnpm и turbo
+используют тот же механизм package script, что и npm; отдельным прогоном не проверялись.
+
+Встроенные профили не меняются (их байты закреплены digest). Для них probe по ID даёт
+проверяемую диагностику вместо EPERM; gate движка работает как прежде. Новый профиль с рецептом —
+новый файл и новый ID.

package/docs/review-protocol.md

@@ -0,0 +1,251 @@
+# Протокол ревью кода: находки, переходы и ошибки протокола
+
+Документ задаёт правила истории находок независимого ревью кода (candidate и
+integration) и отделяет ошибку формата ответа reviewer от содержательного
+отказа. Правила записаны до реализации и являются договором: тесты
+`tests/review-*.test.ts` проверяют именно их.
+
+## 1. Область истории
+
+История находок ведётся **на поручение**, а не на попытку, фазу или SHA:
+
+```
+scope = digestOf({ kind: 'code-review', repositoryId, workId })
+```
+
+- Новая попытка writer, переход candidate → integration и рестарт процесса не
+  начинают историю заново: история каждый раз заново собирается из evidence
+  всех попыток поручения (`ExecutionView.attempts(workId)`) в порядке записи.
+- Отдельного хранилища нет: состояние находок — это записи ревью в
+  `EvidenceRecord` попыток (см. §5). Нового обязательного метода
+  `ExecutionStore`, второй базы или нового пространства локальных записей нет.
+- SHA не является идентичностью истории: после исправления SHA меняется, а
+  находка — нет.
+- Находка другой области (другое поручение или репозиторий) в этой истории
+  неизвестна: ссылка на неё — ошибка протокола `unknown`.
+
+## 2. Идентификатор находки
+
+ID выдаёт controller в момент записи валидного раунда; reviewer его не
+придумывает и ссылается только на выданный. Формат прежний — SHA-256 hex
+(`^[0-9a-f]{64}$`), без ослабления до произвольной строки.
+
+```
+id = digestOf({ v: 1, scope, runId, phase, sha, round, index, severity, message })
+```
+
+`round` — номер валидного раунда области, `index` — позиция находки в ответе.
+Повторно найденный дефект с тем же текстом в новом раунде получает **новый**
+ID: дедупликации по тексту нет, поэтому повторно найденный на integration
+дефект не теряется.
+
+Находка хранит: severity, сообщение, путь/строку, статус (`open`, `closed`,
+`withdrawn`), origin (runId, фаза, SHA, раунд, согласованная постановка
+`spec` на момент записи) и ряд переходов (раунд, runId, фаза, SHA, from → to,
+основание).
+
+## 3. Переходы
+
+Для каждой прежней **открытой** находки валидный ответ называет ровно одну
+запись в `previous` с основанием (`basis`, не короче трёх непробельных
+символов):
+
+| Из                   | В           | Смысл                                                                                  |
+| -------------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `open`               | `closed`    | исправление подтверждено на проверяемом SHA                                            |
+| `open`               | `withdrawn` | находка ошибочна или потеряла предмет; основание объясняет почему                      |
+| `open`               | `open`      | дефект остаётся                                                                        |
+| `closed`/`withdrawn` | `open`      | явное повторное открытие (reopen): дефект снова есть, например в интеграционном дереве |
+
+Закрытые и снятые находки передаются reviewer как история и не требуют
+повторного закрытия. Указать для них `closed`/`withdrawn` повторно —
+ошибка `not-open`.
+
+Ответ невалиден (ошибка протокола), если:
+
+| reason                   | path                               | условие                                                                       |
+| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------------- |
+| `schema`                 | путь Zod, например `previous.0.id` | ответ вне схемы: не SHA-256 ID, пустое основание, неизвестный статус, поля    |
+| `unknown`                | `previous.N.id`                    | ID нет в истории области (в том числе ID чужого поручения/репозитория)        |
+| `duplicate`              | `previous.N.id`                    | ID назван второй раз (в том числе с другим статусом)                          |
+| `not-open`               | `previous.N.status`                | закрытой/снятой находке назван не `open`                                      |
+| `missing`                | `previous`                         | прежняя открытая находка не названа                                           |
+| `approved-with-blocking` | `approved`                         | `approved: true` при новой blocking-находке или blocking, оставшейся открытой |
+
+`note`, оставленная открытой явным переходом, не мешает `approved: true`.
+
+**Атомарность.** Ответ проверяется целиком до любой записи. Невалидный ответ
+не закрывает ни одной находки, не создаёт новых и не даёт PASS: он
+сохраняется только как диагностика (сырой ответ — в своём `review.json`,
+причины — в evidence). Валидный раунд записывается одной транзакцией
+`engine.evidence` под fencing-токеном попытки: попытка, потерявшая владение,
+переходов не сохраняет.
+
+## 4. Фазы, повторное открытие и новая редакция
+
+- Закрытие на candidate не означает одобрения integration: integration —
+  отдельный раунд той же области. Reviewer integration получает открытые
+  находки и историю закрытых; найденный там снова дефект блокирует приёмку
+  либо явным reopen прежнего ID, либо новой находкой с новым ID.
+- Приёмка по-прежнему требует последней записи ревью каждой фазы на точном SHA
+  с PASS (`engine.finish`, `findLast`).
+- **Новая редакция постановки/контрактов** (новое согласование того же
+  поручения) не начинает историю заново и не удаляет её. Открытые находки
+  переносятся в новую редакцию открытыми; в их origin видна редакция, под
+  которой они записаны (`spec`). Reviewer новой редакции обязан назвать их
+  состояние, как любые прежние открытые (например, `withdrawn` с основанием
+  «требование удалено редакцией …»). Закрытые остаются историей. Одобрение
+  прежней редакции новую не подтверждает: новая редакция исполняется новой
+  попыткой, и приёмка учитывает только evidence этой попытки.
+- Формулы host digests (`orderDigest`, `policyDigest`, `scopeDigest`,
+  основание реализации и эпизода) не меняются: находки в них не входят.
+
+## 5. Хранение: аддитивные поля EvidenceRecord
+
+DevContour хранит `Evidence` как есть; все новые поля необязательны, старые
+записи читаются без них.
+
+- `findings[].id`, `findings[].status` — ID и статус находки, записанной этим
+  раундом.
+- `reviewRound` — сведения раунда ревью кода:
+  `version: 1`, `scope`, `round`, `call` (номер вызова reviewer в логическом
+  ревью), `calls` (предел вызовов), `protocol: valid | invalid`, `expected`
+  (ID открытых находок, выданных reviewer), `issues` (path, reason, message —
+  у невалидного), `transitions` (id, from, to, basis — у валидного), `spec`.
+
+Результат (`RunResult`) получает аддитивно: `findings[].id/status` и у ссылок
+на evidence ревью — `review` (round, call, protocol, issues, transitions).
+Принятый результат несёт только решающие записи: невалидные вызовы в него не
+входят отдельными ссылками, их причины видны у валидного вердикта повтора
+(`review.call > 1`, `review.issues` — причины предыдущих вызовов того же
+логического ревью). Непринятый результат содержит и записи невалидных
+вызовов (`review.protocol: invalid` с их причинами).
+
+## 6. Записи alpha.5 (legacy)
+
+Запись ревью без `reviewRound` — запись прежней версии. Её находки (у
+отклонившего ревью) получают детерминированный ID из неизменяемого origin:
+
+```
+id = digestOf({ v: 'legacy-1', scope, evidence: e.id, runId, phase, sha, index, severity, message })
+```
+
+После рестарта ID тот же. Находки открыты, пока reviewer явно не назовёт их
+состояние — это явное повторное ревью вместо пустой истории. Принятые
+попытки и их результаты не переписываются: новые поля у них не появляются, и
+исход не меняется задним числом.
+
+## 7. Ошибка протокола и ограниченный повтор reviewer
+
+| Исход                                                                       | Поведение                                                                                    |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Валидный `approved: false`                                                  | `REVIEW_REJECTED`, обычный путь исправления writer                                           |
+| Нарушение схемы/переходов/противоречивый approved                           | повтор reviewer; после исчерпания — `REVIEW_PROTOCOL_INVALID` (класс infrastructure, exit 4) |
+| Reviewer изменил дерево/HEAD, утрачено владение, отмена, смена согласования | соответствующий отказ без протокольного повтора                                              |
+| Runtime недоступен, авторизация, timeout                                    | прежняя инфраструктурная причина, без протокольного повтора                                  |
+
+- Политика: необязательное поле `reviewProtocolRetries` (0–2). Нет поля —
+  один дополнительный вызов (не более двух вызовов на логическое ревью);
+  `0` отключает повтор. Отсутствующее поле не подставляется в политику, её
+  digest и pins не меняются.
+- Логическое ревью — (область, фаза, SHA). Повтор идёт на том же SHA, с тем же
+  diff, контекстом, назначением reviewer и набором открытых находок; к запросу
+  добавляется только структурированная диагностика (path, reason, message) и
+  требование вернуть полный валидный вердикт. ID не подменяются «похожими»,
+  `previous` не выбрасывается, `approved` не восстанавливается догадкой.
+- Writer не вызывается, номер попытки не растёт. Каждый вызов проходит
+  `measuredInvoke` (бюджет до вызова, учёт usage/стоимости, неизвестная
+  стоимость по `budgets.onUnknown`). Повтор не получает нового предела
+  времени фазы и нового бюджета probe: общий срок и остаток бюджета probe
+  переходят от первого вызова.
+- Каждый вызов пишет свои артефакты: первый — `<phase>/review/`, следующие —
+  `<phase>/review/call-<n>/` (`review.json`, журнал runtime, probe). Каждый
+  невалидный вызов записывается своим evidence (`passed: false`,
+  `reviewRound.protocol: invalid`, без находок); итоговое evidence ссылается
+  на байты валидного вердикта.
+- Рестарт не обнуляет счётчик. Вызов засчитывается при **начале**: запись
+  учёта вызова (`usage`, `CallRecord` со `stage: <фаза>-review`, `runId`)
+  создаётся транзакцией `measuredInvoke` до внешнего invoke, поэтому вызов,
+  прерванный падением controller, засчитан так же, как завершённый (после
+  рестарта он помечается `abandoned`). Начатые вызовы того же (область, фаза,
+  SHA) из попыток, прерванных до вердикта (истёкших или с отказом окружения),
+  засчитываются продолжающей попытке (кандидат переиспользуется); для записей
+  без учёта вызовов — по невалидным evidence. Исчерпанный счётчик — остановка
+  `REVIEW_PROTOCOL_INVALID` без вызова. Номер вызова — номер фактически
+  начатого вызова. Логическое ревью закрывают валидный вердикт или иное
+  завершение попытки (в том числе остановка `REVIEW_PROTOCOL_INVALID`).
+- Срок и бюджет проверок после рестарта не выдаются заново: срок логического
+  ревью — `runTimeoutMs` от начала его первого вызова (по записи учёта);
+  истёкший срок — явная остановка `REVIEW_PROTOCOL_INVALID` (класс `review-protocol`, без автоматического повтора) без вызова, а каждому вызову достаётся
+  только остаток срока. Расход бюджета проверок — по журналам `probes.jsonl`
+  прежних вызовов этого логического ревью. Резерв каждой проверки (её предел)
+  записывается в журнал строкой `start` с fsync **до** запуска команды; без
+  этой записи проверка не запускается. Завершённая проверка списывает
+  фактическое время, начатая без строки исхода (controller или сервер проверок
+  погиб посреди команды) — весь резерв, никогда не меньше. Новый controller
+  останавливает пережившие процессы такой проверки (метка `HARNESS_PROBE_RUN`
+  и их группы) и дописывает строку `abandoned`; остаток меньше секунды — вызов
+  без инструмента проверок (docs/review-probes.md). Integration SHA после рестарта
+  создаётся заново (новое слияние), поэтому это новое логическое ревью; его
+  повторы ограничены правилами повтора попытки.
+- Класс отказа попытки `review-protocol`: автоматического повтора нет
+  (`repairPolicy` — stop), для эпизода восстановления по свойству он
+  нейтрален (не увеличивает и не обнуляет счёт), код остановки результата —
+  `REVIEW_PROTOCOL_INVALID`. Кандидат такой попытки переиспользуется
+  повтором, назначенным человеком, без нового вызова writer.
+
+## 8. План и контракт
+
+`technicalReview` (ревью плана и контракта) применяет то же правило
+атомарности: невалидный ответ (вне схемы или с нарушением `reviewIssues`)
+не применяет переходы и не добавляет находок; раунд записывается
+неодобренным с причинами. Повторно найденная закрытая находка с тем же ID
+открывается снова, а не отбрасывается как дубликат. Формат `ReviewRecord`
+не меняется.
+
+## 9. Адаптеры без протокола переходов (совместимость хостов)
+
+Строгие правила §3 действуют, когда адаптер reviewer объявляет
+`RuntimeCapabilities.reviewProtocol: 1`. Это необязательное поле; нового
+обязательного метода нет. `cliAdapter` (codex, claude, в том числе fixture
+executables `HARNESS_*_BIN`) поле объявляет, поэтому пилот, live и demo
+работают строго. Runner читает поле асинхронно до вызова reviewer, вне
+транзакций хранилища, и кэширует его на runtime. Отказ `capabilities()`
+трактуется как адаптер прежней версии.
+
+Адаптер хоста, который поля не объявляет (например, собственные
+runtime-обёртки DevContour), получает семантику переходов alpha.5:
+
+- в запросе нет раздела выданных ID, и в ответе переходы не требуются:
+  ответ проверяется без прежних открытых находок, как прежний
+  `reviewIssues(result, [])`. Ссылка на прежний ID — `unknown`, а
+  `approved: true` с новой blocking-находкой — `approved-with-blocking`;
+- находки записываются в историю открытыми с выданными ID, раунд помечен
+  `reviewRound.mode: 'legacy'`. Закрытия не выдумываются: одобрение не
+  закрывает прежние находки, они остаются в истории открытыми. Одобрение
+  при таких находках — поведение alpha.5 для этого адаптера: прежний адаптер
+  не умеет называть их состояние;
+- разделение H2 сохраняется: ответ вне схемы или противоречивый `approved`
+  даёт ошибку протокола с ограниченным повтором reviewer и
+  `REVIEW_PROTOCOL_INVALID`, а не содержательный отказ;
+- writer такого поручения не получает раздела «открытых» находок: их
+  некому закрыть.
+
+Если позже ревью ведёт адаптер с протоколом, открытые находки legacy-раундов
+требуют явного перехода, как записи alpha.5 (§6).
+
+### Что реализует собственный адаптер с протоколом
+
+1. `capabilities()` возвращает `reviewProtocol: 1`.
+2. Для `task: 'review-code'` запрос несёт `RuntimeRequest.findings`
+   (`{scope, open[], closed[]}`; у находки — `id`, `severity`, `message`, `path`,
+   `line`, `status`, `origin {runId, phase, sha, round}`, `basis?`). Это те же
+   данные, что раздел запроса `Open review findings issued by the controller`,
+   поэтому адаптеру без модели не нужно разбирать текст.
+3. Ответ (`RuntimeResponse.output`, схема `reviewResultSchema` / wire
+   `reviewOutputSchema`) содержит в `previous` ровно одну запись
+   `{id, status: 'open' | 'closed' | 'withdrawn', basis}` на каждую находку
+   `open`. `id` — выданный (SHA-256 hex), `basis` — не меньше трёх непробельных
+   символов. Для `closed` допустимо только `{id, status: 'open', basis}`
+   (повторное открытие). `approved: true` невозможно при blocking-находке,
+   оставленной открытой, или при новой blocking-находке.