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

package/docs/integrations/hindsight.md

@@ -0,0 +1,148 @@
+# Внешняя память (Hindsight): точка подключения
+
+Статус: **контракт и проверка поддельным провайдером**. Готового
+Hindsight-коннектора в harness нет: нет HTTP-клиента, SDK, MCP-сервера,
+развёртывания сервера и платных обращений. Harness работает без памяти;
+память подключается явно через opt-in entrypoint
+`devcontour-harness/integrations/memory` (исходники — `src/integrations/memory/`).
+Корень пакета и `devcontour-harness/contracts` этот модуль не импортируют
+<!-- repo-only -->(проверяется `tests/memory-availability.test.ts`, `M02/boundary`)<!-- /repo-only -->. Глобально
+
+установленный MCP или Hindsight SDK для пользователей harness не требуется.
+
+## Что есть
+
+| Часть              | API                                                         | Назначение                                                    |
+| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------- |
+| Договор провайдера | `MemoryRecallProvider`, `MemoryRetainProvider`              | два метода, которые реализует будущий адаптер                 |
+| Источник контекста | `memoryContextSource(provider, options)`                    | recall → источник `ContextSnapshot` (`kind: memory`)          |
+| Композиция         | `composeContext(parts, at)`, `mergeSnapshots(...)`          | файлы + память в одном снимке; повтор ID — отказ              |
+| Получатель итога   | `memoryResultSink(provider, options)`                       | обычный `ResultSink` с собственным ключом доставки            |
+| Тестовый провайдер | `src/integrations/memory/testing.ts` (`FakeMemoryProvider`) | детерминированные ответы, счётчики, отказы; только для тестов |
+
+Изменений ядра нет: используются существующие `ContextSource`, `ResultSink`,
+закрепление снимка при согласовании (`context-snapshots` + `approval.context`)
+и записи `delivery` у `Harness.deliver`.
+
+## Recall до согласования
+
+```ts
+import { FileContextSource } from 'devcontour-harness';
+import { composeContext, memoryContextSource } from 'devcontour-harness/integrations/memory';
+
+const memory = memoryContextSource(provider, {
+  id: 'memory', // ID источника в снимке
+  mode: 'optional', // 'required' | 'optional' | 'disabled'
+  bank: 'project-app', // стабильный bank проекта
+  project: 'app',
+  query: 'conventions for greeting module',
+  limits: { maxBytes: 16384, maxItems: 20, maxCostUnits: 5 },
+});
+const context = await composeContext(
+  [{ source: new FileContextSource('context'), ids: ['norms'] }, memory.part()],
+  { repositoryId: 'app' },
+);
+// review-plan → approve → run с этим же снимком
+```
+
+- Recall выполняется в `snapshot`, т.е. до ревью плана и согласования.
+  Исполнение берёт только снимок, связанный с согласованием
+  (`Harness.contextOf`): runner к провайдеру не обращается. Новый ответ
+  памяти после согласования в попытку не попадает; новый снимок при том же
+  графе — `APPROVAL_REQUIRED` (нужно новое ревью плана).
+- Источник памяти закрепляет три файла (все входят в digest источника):
+  - `recall.md` — вкладывается в запрос writer и reviewer; заголовок говорит,
+    что это непроверенные данные, которые не меняют поручение, область,
+    политику и ничего не разрешают;
+  - `provenance.json` (в поле `references`: закреплён, но не вкладывается):
+    провайдер и его версия, mode, bank, project, query, `recalledAt`,
+    digest/размер/число элементов/стоимость фактического ответа, пределы,
+    применённый объём и признаки обрезки (`truncated.items`, `truncated.bytes`,
+    `truncated.omitted`);
+  - `response.json` (тоже в `references`) — фактические байты тела ответа провайдера (если не
+    больше предела файла снимка; иначе остаётся только digest в provenance).
+- Пределы: элементы берутся по порядку провайдера целиком. Превышение
+  `maxItems`/`maxBytes`: у `required` по умолчанию — отказ подготовки
+  (`truncation: 'forbid'`), у `optional` — отбрасывание с явной строкой
+  `[TRUNCATED by harness: …]` в `recall.md` и в provenance. Элемент с
+  `mandatory: true` не отбрасывается никогда: его обрезка — отказ
+  (`required`) или отсутствие источника (`optional`). Стоимость больше
+  `maxCostUnits` — так же.
+- Режимы недоступности (ошибка, таймаут, ответ не JSON или вне схемы):
+  - `required` — `HarnessError NOT_READY` с причиной до ревью/согласования;
+    пустой «успешный» ответ не подставляется. Если ID памяти указан в
+    `order.context`, снимок без неё не пройдёт ни `run`, ни `review-plan`;
+  - `optional` — запись в `snapshot.missing` с причиной; снимок
+    согласуется и исполняется без памяти;
+  - `disabled` — провайдер не вызывается и может не передаваться вовсе;
+    снимок совпадает со снимком без памяти.
+- Память — контекст, а не постановка: она не меняет `WorkOrder`, write
+  scope, gates, политику и approval digest. Непроверенный дневник writer
+  (его `summary`) reviewer не передаётся: reviewer получает diff, evidence
+  controller и тот же закреплённый контекст.
+
+## Запись подтверждённого итога
+
+```ts
+const sink = memoryResultSink(provider, { bank: 'project-app', project: 'app' });
+await harness.deliver(workId, sink); // отдельно от Relay/файлового получателя
+```
+
+- `sink.id` по умолчанию `memory-<provider.id>`: ключ доставки
+  `<sink>:<work>:<run>` отдельный, состояние видно в `result().delivery` и
+  событиях `delivery.*` с этим `sink`. Сбой памяти не откатывает Git
+  accepted и не меняет receipt других получателей. Повтор
+  `Harness.deliver(work, sink)` отправляет только память; writer, reviewer и
+  другие получатели не вызываются. Общей распределённой транзакции нет.
+- Сохраняются только `accepted` результаты; остальные исходы получают
+  receipt `skipped: …` без обращения к провайдеру.
+- Содержимое — итог controller (исход, SHA, gates, находки), не пересказ writer.
+
+### Identity: bank, document_id, operation_id
+
+| Идентичность   | Как получается                                                                              | Гарантия                                                                                                                                         |
+| -------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| bank           | стабильный по проекту (`options.bank`), задаётся оператором                                 | память одного проекта не смешивается с другими                                                                                                   |
+| `document_id`  | `dch-` + digest(provider, bank, project, work, run, digest результата) — `memoryDocumentId` | повтор того же результата — **upsert** того же документа (в Hindsight `update_mode: replace` по умолчанию удаляет прежний документ и его память) |
+| `operation_id` | UUID (форма v5) из digest(ключ доставки, document_id) — `uuidOf`                            | повтор **асинхронного** retain с тем же `operation_id` возвращает прежнюю операцию и не создаёт новой работы                                     |
+
+Это разные гарантии: upsert документа не мешает серверу повторно выполнить
+асинхронную обработку (извлечение фактов, расход LLM), а `operation_id` не
+задаёт идентичность документа. Адаптер должен передавать оба.
+
+## Что проверить при создании реального адаптера
+
+Сверено с публичной документацией https://hindsight.vectorize.io
+(`/developer/api/retain`, `/developer/api/recall`, на 2026-10-22 указана
+версия документации 1.1); **на конкретном сервере не проверялось**:
+
+- retain принимает `content`, `document_id`, `async`, `operation_id` (UUID),
+  `context`, `timestamp`, `metadata`, `tags`, `update_mode`; операции
+  async — `GET /v1/default/banks/{bank_id}/operations`; ответ async не
+  содержит usage;
+- recall принимает `query` (до 500 токенов), `budget`, `max_tokens`, `types`,
+  `tags`; ответ `results[]` с `id`, `text`, `document_id`, `scores`; бюджет
+  ответа задаётся токенами, а не числом элементов.
+
+Обязательные проверки адаптера (не реализованы, статус «to verify»):
+
+1. Версия API и capabilities сервера: поддержка `operation_id` для
+   идемпотентного async retain и `document_id` upsert в используемой
+   версии; без поддержки `operation_id` повтор async retain не считается
+   идемпотентным — адаптер должен ждать операцию синхронно или сообщать
+   неизвестный исход.
+2. Отображение `MemoryLimits` на `max_tokens`/`budget` и перевод `results[]`
+   в `memoryRecallBodySchema` (тело ответа закрепляется как получено).
+3. Учёт: стоимость recall/retain (`costUnits`, `usage` источника и
+   получателя) ведётся отдельно от usage coding runtime и бюджетов попыток.
+4. Ключи и адрес сервера — только у выбранного адаптера; без них core,
+   файловый сценарий и `mode: 'disabled'` работают.
+
+## Проверка
+
+<!-- repo-only -->В репозитории harness: `node --import tsx --test tests/memory-*.test.ts`<!-- /repo-only --> — M01 (одинаковые
+
+закреплённые байты у writer и reviewer, смена ответа после согласования,
+пределы), M02 (required/optional/disabled с одним недоступным провайдером),
+M03 (независимая доставка памяти и повтор только её). Используется обычный
+путь `review-plan → approve → run` с fixture runtime.

package/docs/quickstart.md

@@ -13,7 +13,7 @@
 ```sh
 mkdir harness-demo && cd harness-demo
 npm init -y >/dev/null
-npm install --save-exact devcontour-harness@0.1.0-alpha.5
+npm install --save-exact devcontour-harness@0.1.0-alpha.6
 npx harness --version
 npx harness doctor
 ```

package/docs/release-notes/0.1.0-alpha.6.md

@@ -0,0 +1,238 @@
+# devcontour-harness 0.1.0-alpha.6
+
+Этот выпуск добавляет:
+
+- переносимые инструменты целевого проекта: npm, pnpm, Turborepo, Go и
+  Python/uv;
+- рецепт Turbo Starter;
+- общий контракт внешнего источника заданий и доставки с двумя opt-in
+  транспортами Relay;
+- протокол истории находок ревью кода;
+- нейтральную точку подключения внешней памяти.
+
+Ядро — Engine, Runner, файловые источник и получатель, standalone CLI —
+работает как раньше. Интеграции подключаются только явно, через отдельные
+входы пакета. Пакет не публикуется автоматически.
+
+## Новые входы пакета
+
+| Вход                                        | Назначение                                                     |
+| ------------------------------------------- | -------------------------------------------------------------- |
+| `devcontour-harness/toolchains`             | рецепты установки, пробы версий, диагностика (`inspectPolicy`) |
+| `devcontour-harness/integrations/connector` | общий контракт источника и доставки, состояние коннектора      |
+| `devcontour-harness/integrations/relay-v1`  | транспорт Relay v1 (HTTP)                                      |
+| `devcontour-harness/integrations/relay-v2`  | транспорт Relay-2 (subprocess CLI)                             |
+| `devcontour-harness/integrations/memory`    | дополнительный `ContextSource` памяти и получатель итога       |
+
+Корень пакета и `./contracts` эти модули не импортируют. CLI загружает
+коннектор и адаптер транспорта только для явно выбранного provider.
+
+## Изменения API и поведения
+
+### CLI
+
+- `source-check` — проверка подключения, проекта, capabilities и mapping;
+  только чтение.
+- `source-snapshot --out <dir> [--policy]` — закреплённый снимок задач:
+  `graph.json`, `context.json`, `manifest.json`.
+- `source-status` — локальный и внешний статус доставки.
+- `source-deliver [--work]` — повтор или продолжение доставки с тем же ключом
+  операции.
+- `source-reconcile --operation <key> [--decision resend|adopt:<id>|recheck]` —
+  явный разбор неизвестного исхода или конфликта.
+- `run --source <connector.json>`: задачи перечитываются, их semantic digest
+  сверяется с закреплённым снимком, eligibility проверяется. Всё это —
+  до любого вызова runtime.
+- `review-plan --source`: внешние предпосылки допускаются по решению
+  источника (`trusts`) и доступности SHA в target ref — те же правила, что у
+  `run`. Без `--source` поведение прежнее.
+- `cleanup --state --run` — довести незавершённую очистку попытки.
+- `run` выполняет обязательный preflight toolchain: при любой проблеме
+  диагностики попытка не начинается.
+
+Прежние команды и их коды выхода не изменились.
+
+### Доставка
+
+- `DeliveryOutcome` получил необязательный вариант
+  `{ status: 'uncertain', operation, reason }`. Прежние получатели
+  (`delivered` / `conflict`) компилируются и работают без изменений.
+- `DeliveryState`: значение статуса `uncertain` и необязательное поле
+  `operation`.
+- Новое событие журнала `delivery.uncertain`:
+  `{ sink, key, revision, attempts, operation, reason }`.
+- Повтор доставки не отправляет мутацию, пока неизвестный исход не разобран
+  (`source-reconcile`).
+- Протокол коннектора: намерение сохраняется до внешнего вызова, затем
+  read-back по маркеру, затем receipt.
+  - Подтверждённый отказ получателя — безопасный повтор.
+  - Неизвестный исход — `uncertain`, без автоматического повтора.
+  - Перед каждым неподтверждённым шагом сверяется snapshot: старая постановка
+    не закрывает новую; чужое изменение между сверкой и CAS даёт конфликт.
+- Состояние коннектора — отдельный SQLite
+  `<state>/connectors/<provider>-<hash>.sqlite`. Это не вторая база
+  исполнения.
+- Секреты маскируются в ошибках транспорта, проблемах `source-check` и
+  причинах шагов.
+
+### Протокол ревью кода
+
+Подробно — [review-protocol](../review-protocol.md).
+
+**История находок.**
+
+- Находки ведутся на поручение (область = поручение + репозиторий), а не на
+  попытку или SHA.
+- ID находки выдаёт controller; reviewer называет состояние каждой открытой
+  находки (`previous`).
+- Записи ревью получили необязательные поля: `EvidenceRecord.reviewRound` и
+  `findings[].id/status`. В `RunResult.evidence[]` — `findings[].id/status` и
+  `review`.
+- На одном SHA и фазе бывает несколько записей ревью: невалидная, затем
+  валидная. Это не отказ задачи.
+
+**Ошибка протокола.**
+
+- Ошибка формата ответа reviewer отделена от содержательного отказа.
+- Reviewer вызывается повторно ограниченное число раз, writer при этом не
+  вызывается. Затем — код `REVIEW_PROTOCOL_INVALID` (класс infrastructure,
+  exit 4) и вид отказа попытки `review-protocol`. Автоматического повтора
+  попытки нет.
+- Политика: необязательное поле `reviewProtocolRetries` (0–2, по умолчанию 1).
+  Значение по умолчанию в политику не подставляется.
+
+**Совместимость адаптеров.**
+
+- `RuntimeCapabilities.reviewProtocol?: 1` — строгий протокол для адаптера,
+  который его объявляет. `cliAdapter` (codex, claude, fixture executables) его
+  объявляет.
+- Адаптер хоста без этого поля получает семантику alpha.5: раунд помечается
+  `legacy`, переходы не требуются. Поэтому прежние runtime-обёртки хоста
+  работают без изменений.
+- `RuntimeRequest.findings` — открытые и закрытые находки для адаптера с
+  протоколом.
+
+**Проверки reviewer.** `run_check` принимает `{"gate": "<id>"}`: controller
+исполняет объявленный gate (его argv, cwd, окружение, путь отчёта во
+временном каталоге) без записи в исходники. Другой вид — исследовательский
+`{"argv": [...]}`. Подробно — [review-probes](../review-probes.md).
+
+### Gates и отчёты
+
+- Каждый gate `kind: test` получает `TURBO_FORCE=true` и `-count=1` в конце
+  `GOFLAGS`. Дочерние процессы наследуют оба значения, поэтому они действуют
+  через любую обёртку, в библиотеке и в CLI.
+- Это только заставляет тесты выполниться заново и не меняет смысл
+  результата. Значения записываются в заголовок журнала gate (`fresh=…`).
+- Gates `kind: check` не изменились.
+- JUnit: атрибуты `name`/`classname` декодируются один раз, включая двойное
+  экранирование `"` репортером Node.js 24. Testcase с кавычками в имени теперь
+  сопоставляется с `testId` критерия.
+
+### Инструменты целевого проекта (toolchains)
+
+- `repositories[].toolchain`: `tools` — проверенные версии, `packageManagers` —
+  явный выбор менеджера по каталогу. Поле необязательное, аддитивное.
+- Новые встроенные профили: `npm-ci`, `pnpm-frozen`, `go-gotestsum`,
+  `python-uv`. Прежние профили побайтно те же, их закрепления не изменились.
+- `doctor --policy` добавляет `toolchains[]`: план шагов и gates, инструменты
+  и их версии, lockfiles, отчёты, неоднозначности, проблемы с кодом и полем.
+- Диагностика только читает файлы и запускает ограниченные пробы версий
+  (`--version`).
+- Путь инструмента разрешается до канонического. Инструмент внутри
+  репозитория или каталога состояния не запускается (`TOOL_IN_PROJECT`).
+- Диапазон версии в `package.json` допустим, если lockfile закрепляет точную
+  версию.
+- Подробно — [toolchains](../toolchains.md).
+
+### Turbo Starter
+
+- Рецепт для Turbo Starter на закреплённом commit.
+- В архиве:
+  - `examples/turbo-starter/`: политика, граф, приёмочные тесты с JUnit,
+    шаблоны env, подготовленные изменения;
+  - lifecycle-мост `compose-bridge`: PostgreSQL на попытку и фазу, с порядком
+    принятия и очистки;
+  - оверлей controller mode в `templates/controller-mode/`.
+- Upstream не патчится.
+- Подробно — [turbo-starter](../turbo-starter.md).
+
+### Точка подключения памяти
+
+- Договор провайдера: `MemoryRecallProvider` и `MemoryRetainProvider`.
+- `memoryContextSource` — recall как источник `ContextSnapshot`.
+- `composeContext` / `mergeSnapshots` — файлы и память в одном закреплённом
+  снимке.
+- `memoryResultSink` — запись подтверждённого итога с собственным ключом.
+- Изменений ядра нет; без памяти harness работает как прежде.
+- Подробно — [hindsight](../integrations/hindsight.md).
+
+## Совместимость
+
+- **Прежние потребители.**
+  - Реализации портов в форме alpha.5 проходят проверку типов против `.d.ts`
+    архива: `WorkSource`, `ContextSource`, `ResultSink` без `uncertain`,
+    `ExecutionHost` без необязательных портов, `ExecutionStore` из четырёх
+    методов.
+  - С ними проходит файловый сценарий через CLI, `Harness.run` и
+    `Engine`/`Runner`.
+  - Регистрация Relay или памяти и новый обязательный метод хоста не нужны.
+- **Основания согласований.**
+  - Digest политик, графов, поручений и контекста прежних примеров совпадают
+    со значениями alpha.5.
+  - Политика без новых полей (`toolchain`, `reviewProtocolRetries`) сохраняет
+    `policyDigest`, `executionDigest` и закрепления. Политика с ними получает
+    новое основание явно (новое согласование).
+- **Состояние alpha.5.** alpha.6 читает его без преобразования:
+  - результат, журнал и записи доставки читаются так же, строки базы не
+    меняются;
+  - прежние записи ревью — legacy-раунды;
+  - receipts и история не переписываются.
+- **Откат.**
+  - Standalone-состояние с новыми полями — записи ревью с `reviewRound`,
+    доставка `uncertain` — alpha.5 и alpha.4 не читают: отказ
+    `STATE_VERSION_UNSUPPORTED` до любой записи.
+  - Хост DevContour с адаптером alpha.4 такое состояние открывает без отказа
+    и пишет в него роль controller и события. Новые поля при этом
+    сохраняются, потери данных нет, но строгой гарантии нет.
+  - Откат с alpha.6 в обоих случаях — только восстановлением копии состояния,
+    сделанной до обновления. Матрица — [upgrade](../upgrade.md).
+- **Версия движка.** Номер версии — это `engineVersion`. Правила
+  alpha.2–alpha.5 действуют и между alpha.5 и alpha.6: `CONTROLLER_BUSY`, а
+  `LEASE_STALE` — до истечения срока и recovery.
+- **DevContour.**
+  - Прежняя встройка (vendored архив, `vendor-harness.mjs`) работает с новым
+    архивом без изменений DevContour: собственные runtime-обёртки DevContour
+    не объявляют `reviewProtocol` и сохраняют семантику ревью alpha.5.
+  - Переход DevContour на протокол ревью — отдельное изменение его адаптеров.
+- Проверенные версии инструментов —
+  [compatibility-versions](../compatibility-versions.md).
+
+## Известные ограничения
+
+- Ядро наблюдает процессы системными `ps`, `lsof` и `sysctl`. С alpha.6 они
+  ищутся по штатным путям ОС (`/bin/ps`, `/usr/sbin/lsof`, `/usr/sbin/sysctl`
+  и т. п.), а не через PATH: PATH из одних `node` и `git` достаточен. Только
+  если ни одного штатного пути нет (нестандартная ОС), используется PATH. В
+  песочнице, запрещающей запуск `ps`, containment невозможен — это отказ
+  окружения.
+- **Relay-2 на macOS** требует SQLite не ниже 3.44. Системная библиотека
+  старше: путь к новой задаётся в `relay.env` коннектора (`DYLD_LIBRARY_PATH`).
+- Доставка не обещает distributed exactly-once. У получателя нет
+  идемпотентности по запросу, Git и Relay не образуют общей транзакции.
+  Неоднозначные случаи решает оператор (`source-reconcile`).
+- Гарантия одного владельца доставки действует только для процессов с общим
+  каталогом состояния коннектора. Независимые установки с разными каталогами
+  состояния вне гарантии и могут доставить одну операцию дважды; это видно в
+  `ownership` у `source-check`/`source-status`.
+- Готового Hindsight-адаптера нет: только договор, композиция и проверка
+  поддельным провайдером.
+- Встроенные профили `npm-ci`, `pnpm-frozen`, `go-gotestsum` и `python-uv`
+  задают путь отчёта жёстко. В проверке reviewer `{"gate": …}` такой gate
+  возвращает диагностику окружения с рецептом; gates движка работают как
+  обычно.
+- На macOS отмена может не найти отсоединённого не-node потомка, запущенного
+  менее чем за 250 мс до отмены (опрос `ps -E`).
+- **Ограничения Turbo Starter upstream.** `pnpm env:check` падает на
+  Node 24.3.0. `check-types` admin-панели скачивает пакет через `npx` (нужна
+  сеть). Изоляция gates в примере выключена.

package/docs/review-probes.md

@@ -0,0 +1,120 @@
+# Проверки 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.
+
+## Рецепт: путь отчёта из переменной 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.