devcontour-harness 0.1.0-alpha.30 → 0.1.0-alpha.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +43 -16
  2. package/docs/architecture.md +12 -0
  3. package/docs/compatibility.md +21 -18
  4. package/docs/contracts.md +270 -12
  5. package/docs/release-notes/0.1.0-alpha.31.md +44 -0
  6. package/docs/release-notes/0.1.0-alpha.32.md +33 -0
  7. package/docs/release-notes/0.1.0-alpha.33.md +29 -0
  8. package/docs/release-notes/0.1.0-alpha.34.md +32 -0
  9. package/docs/upgrade.md +181 -0
  10. package/lib/agents/cli-adapter.js +1 -0
  11. package/lib/cli.js +25 -3
  12. package/lib/contracts/cli.d.ts +1381 -18
  13. package/lib/contracts/cli.js +43 -1
  14. package/lib/contracts/diagnosis.d.ts +2 -1
  15. package/lib/contracts/diagnosis.js +1 -0
  16. package/lib/contracts/events.d.ts +760 -5
  17. package/lib/contracts/events.js +109 -3
  18. package/lib/contracts/execution.d.ts +112 -1
  19. package/lib/contracts/execution.js +38 -0
  20. package/lib/contracts/failure.d.ts +6 -1
  21. package/lib/contracts/failure.js +5 -1
  22. package/lib/contracts/handoff.d.ts +702 -0
  23. package/lib/contracts/handoff.js +305 -0
  24. package/lib/contracts/index.d.ts +1 -0
  25. package/lib/contracts/index.js +1 -0
  26. package/lib/contracts/policy.d.ts +27 -1
  27. package/lib/contracts/policy.js +38 -2
  28. package/lib/contracts/published.d.ts +1016 -3
  29. package/lib/contracts/published.js +2 -0
  30. package/lib/contracts/repair-policy.js +5 -0
  31. package/lib/contracts/report.d.ts +118 -2
  32. package/lib/contracts/report.js +61 -3
  33. package/lib/control/base-move.d.ts +7 -2
  34. package/lib/control/base-move.js +14 -1
  35. package/lib/control/harness.d.ts +81 -19
  36. package/lib/control/harness.js +8 -93
  37. package/lib/control/recovery.d.ts +1 -1
  38. package/lib/control/status.d.ts +235 -0
  39. package/lib/control/status.js +101 -0
  40. package/lib/engine/budget.d.ts +78 -0
  41. package/lib/engine/budget.js +13 -2
  42. package/lib/engine/classify.d.ts +14 -1
  43. package/lib/engine/classify.js +34 -0
  44. package/lib/engine/engine.d.ts +31 -11
  45. package/lib/engine/engine.js +99 -5
  46. package/lib/engine/joint-runner.d.ts +6 -0
  47. package/lib/engine/joint-runner.js +20 -4
  48. package/lib/engine/property-recovery.js +1 -0
  49. package/lib/engine/reuse.js +1 -0
  50. package/lib/engine/runner.d.ts +8 -0
  51. package/lib/engine/runner.js +120 -16
  52. package/lib/engine/stall-sweep.d.ts +137 -0
  53. package/lib/engine/stall-sweep.js +393 -0
  54. package/lib/environment/activity.d.ts +34 -0
  55. package/lib/environment/activity.js +55 -0
  56. package/lib/environment/isolation.d.ts +67 -3
  57. package/lib/environment/isolation.js +148 -5
  58. package/lib/environment/lifecycle.js +2 -1
  59. package/lib/environment/process.d.ts +7 -1
  60. package/lib/environment/process.js +14 -0
  61. package/lib/environment/redaction.d.ts +2 -0
  62. package/lib/environment/redaction.js +19 -0
  63. package/lib/explain/state.d.ts +26 -5
  64. package/lib/explain/state.js +41 -0
  65. package/lib/handoff/index.d.ts +2 -0
  66. package/lib/handoff/index.js +3 -0
  67. package/lib/handoff/markdown.d.ts +6 -0
  68. package/lib/handoff/markdown.js +155 -0
  69. package/lib/handoff/pack.d.ts +79 -0
  70. package/lib/handoff/pack.js +531 -0
  71. package/lib/index.d.ts +19 -3
  72. package/lib/index.js +18 -1
  73. package/lib/integrations/connector/redact.d.ts +2 -13
  74. package/lib/integrations/connector/redact.js +2 -21
  75. package/lib/integrations/connector/testing.js +1 -1
  76. package/lib/projections/attempt.d.ts +28 -0
  77. package/lib/projections/attempt.js +14 -0
  78. package/lib/projections/next.d.ts +3 -1
  79. package/lib/projections/next.js +4 -1
  80. package/lib/projections/stop.d.ts +22 -1
  81. package/lib/projections/stop.js +73 -15
  82. package/lib/report/compute.js +229 -21
  83. package/lib/report/document.js +31 -7
  84. package/lib/storage/document.d.ts +28 -6
  85. package/lib/storage/sqlite.d.ts +2 -0
  86. package/lib/storage/sqlite.js +9 -1
  87. package/lib/verification/gates-at.d.ts +11 -1
  88. package/lib/verification/gates-at.js +28 -2
  89. package/lib/verification/gates.d.ts +3 -1
  90. package/lib/verification/gates.js +25 -4
  91. package/package.json +1 -1
  92. package/schemas/execution-document.schema.json +68 -0
  93. package/schemas/execution-policy.schema.json +32 -0
  94. package/schemas/handoff-pack.schema.json +1430 -0
  95. package/schemas/run-event.schema.json +679 -0
  96. package/schemas/stop-diagnosis.schema.json +1 -0
  97. package/schemas/value-report.schema.json +236 -3
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.30` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.34` — предварительный выпуск (alpha). Договоры
9
9
  > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
10
10
  > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
11
11
  > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
28
28
  Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
29
29
 
30
30
  ```sh
31
- npm install --save-exact devcontour-harness@0.1.0-alpha.30 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.34 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -90,19 +90,20 @@ git rev-parse refs/heads/harness/accepted # совпадает с data.result.
90
90
 
91
91
  ## Команды
92
92
 
93
- | Команда | Что делает |
94
- | -------------------------------------------- | -------------------------------------------------- |
95
- | `validate --graph F --policy F` | Проверка входов без моделей и записи |
96
- | `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
97
- | `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
98
- | `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
99
- | `status / events / result --state D` | Чтение без побочных эффектов |
100
- | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
- | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
- | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
103
- | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
104
- | `doctor` | Версии, runtime, sandbox, совместимость состояния |
105
- | `report --state D [--format md\|html]` | Отчёт об эффекте по данным проекта |
93
+ | Команда | Что делает |
94
+ | ----------------------------------------------- | -------------------------------------------------- |
95
+ | `validate --graph F --policy F` | Проверка входов без моделей и записи |
96
+ | `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
97
+ | `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
98
+ | `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
99
+ | `status / events / result --state D` | Чтение без побочных эффектов |
100
+ | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
+ | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
+ | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
103
+ | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
104
+ | `doctor` | Версии, runtime, sandbox, совместимость состояния |
105
+ | `report --state D [--format md\|html]` | Отчёт об эффекте по данным проекта |
106
+ | `handoff --state D [--format md] [--intent T]…` | Пакет передачи контекста новой сессии агента |
106
107
 
107
108
  stdout — один JSON (`devcontour-harness/v1alpha1`), диагностика — stderr. Exit
108
109
  codes: 0 успех, 2 неверный вход, 3 отказ/блокировка, 4 инфраструктура.
@@ -128,7 +129,8 @@ codes: 0 успех, 2 неверный вход, 3 отказ/блокиров
128
129
  каталог в отчёт не попадают; `--no-titles` убирает и заголовки. Тот же
129
130
  каталог — те же байты: момент отчёта — последняя метка времени в данных.
130
131
  Хост строит тот же отчёт из своего хранилища: `valueReport` из
131
- `devcontour-harness/report`. Подробно — [ValueReport](docs/contracts.md#valuereport).
132
+ `devcontour-harness/report`, файл отчёта — `writeReportFile` из корня пакета.
133
+ Подробно — [ValueReport](docs/contracts.md#valuereport).
132
134
 
133
135
  ## Библиотека
134
136
 
@@ -146,6 +148,31 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
146
148
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
147
149
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
148
150
 
151
+ ## Выпуск 0.1.0-alpha.34
152
+
153
+ События повторов, отмен, сдвигов базы и причин отказа среды; отчёт об
154
+ эффекте различает ручные и автоматические действия. Подробно —
155
+ [заметки выпуска](docs/release-notes/0.1.0-alpha.34.md).
156
+
157
+ ## Выпуск 0.1.0-alpha.33
158
+
159
+ Пакет передачи и `explain` без ложных решений по отменённым работам и без
160
+ повтора расхода ревью плана у каждого поручения. Подробно —
161
+ [заметки выпуска](docs/release-notes/0.1.0-alpha.33.md).
162
+
163
+ ## Выпуск 0.1.0-alpha.32
164
+
165
+ Пакет передачи контекста для хоста без экземпляра `Harness` и под его предел
166
+ ответа, экспорт `policySecrets` и `writeReportFile`, песочница при глубоком
167
+ TMPDIR. Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.32.md).
168
+
169
+ ## Выпуск 0.1.0-alpha.31
170
+
171
+ Controller сам замечает зависшие попытки и проверки (`stallSweep`, отказ
172
+ `stalled`), а `harness handoff` собирает пакет передачи контекста новой сессии
173
+ агента из хранилища.
174
+ Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.31.md).
175
+
149
176
  ## Выпуск 0.1.0-alpha.30
150
177
 
151
178
  Отчёт об эффекте `harness report`, события стадий и `status --detail` для
@@ -648,6 +648,18 @@ executable. Live smoke — отдельный opt-in с явно заданны
648
648
  вложенные `.git` на любой глубине тоже закрыты (на Linux — только
649
649
  существующий файл `.git`). Дерево больше предела перечисления — отказ
650
650
  проверки классом `environment`, а не молча урезанные запреты.
651
+ Свои unix-сокеты srt создаёт во временном каталоге своего процесса, а путь
652
+ сокета ограничен (`sun_path`: 104 байта на macOS, 108 на Linux). Если путь
653
+ в TMPDIR процесса не укладывается, srt получает свой каталог под `/tmp`
654
+ (`dc-srt-<pid>-*`, `mkdtemp`, `0700`), который удаляется после проверки;
655
+ каталоги, брошенные упавшим controller (свои, ни каталог, ни записи прямо
656
+ в нём не менялись дольше суток, процесс создателя завершён), убираются при
657
+ создании нового — через переименование в `.dc-srt-rm-*` и повторную
658
+ проверку. Свежая запись внутри держит каталог: srt переживает controller,
659
+ убитый SIGKILL, а контейнер с общим `/tmp` не видит создателя из другого
660
+ пространства pid. Команде внутри
661
+ по-прежнему передаётся её scratch. Не создаётся и этот каталог — отказ
662
+ проверки классом `environment` с TMPDIR в тексте до запуска команды.
651
663
  - **Сверка защищённых путей.** Запреты песочницы проверяют только путь
652
664
  операции: каталог, собранный в `node_modules` и перенесённый в дерево
653
665
  проекта, ими не закрыт. До и после каждого gate и вокруг работы исполнителя
@@ -42,9 +42,11 @@ coordinator. `Store.change(type, fn)` открывает `BEGIN IMMEDIATE` (вл
42
42
  `Store.change` события не записал, а у транзакции есть нейтральные
43
43
  события. Изменения остальных методов `Store` не требуется.
44
44
  Транзакции только локальных записей (`workflow.updated`, `usage.recorded`,
45
- `checks.recorded`) и `base.moved` (проверка владения и сдвиг ref)
46
- событий не создают: адаптер выполняет их как `Store.atomic` без
47
- `Store.change`, как DevContour сейчас пишет учёт вызовов и очередь ведущего.
45
+ `checks.recorded`) событий не создают: адаптер выполняет их как
46
+ `Store.atomic` без `Store.change`, как DevContour сейчас пишет учёт вызовов
47
+ и очередь ведущего. `base.moved` (проверка владения и сдвиг ref) записей не
48
+ меняет, но пишет событие `base.moved`: адаптер добавляет его
49
+ `Store.appendEvent`, как любое нейтральное событие без изменения документа.
48
50
  5. **Курсор.** `seq` нейтрального события = `id события журнала × 1024 + индекс` (не больше 1024 событий на транзакцию — с запасом для графа из 500 поручений; больше — отказ транзакции).
49
51
  `ExecutionStore.events(after)` строит `RunEvent` из `harnessEvents` строго
50
52
  по возрастанию `seq`; события прежних версий без `harnessEvents` в
@@ -148,21 +150,22 @@ Standalone-хост использует `digestOf` (SHA-256 каноничес
148
150
 
149
151
  ## Сохраняемые форматы
150
152
 
151
- | Что | Правило |
152
- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
- | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
154
- | Типы событий журнала | Прежние строки, см. `transactionKinds` |
155
- | События стадий | Тип `attempt.stage` (не выпущено): границы стадий попытки: `started` и не больше одного `finished` на замер `AttemptState.timings` (стадия утратившей владение попытки остаётся открытой); документ состояния и digest политики прежние. Тип, которого читатель не знает, читается как `{type: 'unknown', original}` без нагрузки. Версии до этой событие разбирают строго: после отката ниже неё `events` отказывает на странице с ним (upgrade.md) |
156
- | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
157
- | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
158
- | Receipt среды | `environment.json` `version: 1` |
159
- | Отчёт свойств, договор проверки, корпус | `version: 1` |
160
- | Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
161
- | Artifacts gates | Необязательное `repositories[].gates[].artifacts`: без поля политика и её digest прежние. Поле `artifactFiles` в evidence gate и в записи совместной проверки необязательно: прежние записи читаются как есть |
162
- | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
163
- | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
164
- | Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
165
- | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
153
+ | Что | Правило |
154
+ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
155
+ | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
156
+ | Типы событий журнала | Прежние строки, см. `transactionKinds` |
157
+ | События стадий | Тип `attempt.stage` (не выпущено): границы стадий попытки: `started` и не больше одного `finished` на замер `AttemptState.timings` (стадия утратившей владение попытки остаётся открытой); документ состояния и digest политики прежние. Тип, которого читатель не знает, читается как `{type: 'unknown', original}` без нагрузки. Версии до этой событие разбирают строго: после отката ниже неё `events` отказывает на странице с ним (upgrade.md) |
158
+ | События вмешательств и причин отказа | Типы `work.retried`, `work.cancelled`, `base.moved`, `attempt.diagnosed` (не выпущено): актёр повтора, отмены и сдвига базы, причина отказа окружения; пишутся в транзакции изменения. Документ состояния и digest политики прежние. Версии с терпимым чтением (alpha.30 и новее) читают их как `{type: 'unknown', original}`; ниже — `events` отказывает на странице с ними (upgrade.md). Перечни `cause` и `by` строгие: новое значение в будущей версии — изменение договора, и эта версия отклонит такое событие при чтении (известный тип с нарушенной нагрузкой), поэтому новое значение добавляется только вместе с новым типом события или с изменением правила чтения |
159
+ | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
160
+ | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
161
+ | Receipt среды | `environment.json` `version: 1` |
162
+ | Отчёт свойств, договор проверки, корпус | `version: 1` |
163
+ | Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
164
+ | Artifacts gates | Необязательное `repositories[].gates[].artifacts`: без поля политика и её digest прежние. Поле `artifactFiles` в evidence gate и в записи совместной проверки необязательно: прежние записи читаются как есть |
165
+ | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
166
+ | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
167
+ | Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
168
+ | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
166
169
 
167
170
  ## Переменные окружения gates
168
171
 
package/docs/contracts.md CHANGED
@@ -33,7 +33,8 @@ refs, варианты исходов. Связи **между** значени
33
33
  Опубликованы: `work-order`, `work-graph`, `execution-policy`,
34
34
  `context-snapshot`, `contract-document`, `run-result`, `result-envelope`,
35
35
  `run-event`, `review-record`, `joint-verification`, `execution-document`,
36
- `value-report` (отчёт `harness report`, см. «ValueReport»).
36
+ `value-report` (отчёт `harness report`, см. «ValueReport»), `handoff-pack`
37
+ (пакет `harness handoff`, см. «HandoffPack»).
37
38
 
38
39
  ## Версии
39
40
 
@@ -108,6 +109,7 @@ manifest снимка и в необязательном поле `baseline` о
108
109
  | `toolProfiles{}`, `environment`, `lifecycle`, `resources[]` | Инструменты (у профиля — встроенные инструменты claude, shell и сеть codex, MCP-серверы `mcp{}`: stdio-команда или http-адрес, только перечисленные `tools`, учётные данные — именами переменных `env`/`bearerTokenEnv`, передаются CLI по имени), среда, ресурсы (порты 1024–65535) |
109
110
  | `concurrency`, `leaseMs`, `runTimeoutMs`, `reviewProbes` | Пределы исполнения |
110
111
  | `maxAttempts`, `repairBudget`, `reuseImplementation` | Повторы и повторное использование кандидата |
112
+ | `stallSweep{intervalMs, quietMs, stalledMs, action}` | Необязательное: обход зависших попыток controller ([ниже](#зависшие-попытки)); нет поля — 30 000 / 180 000 / 600 000 мс и `report`, умолчание не подставляется и digest политики не меняет |
111
113
  | `reviewProtocolRetries` | Необязательное: дополнительные вызовы reviewer кода при ошибке протокола ответа (0–2; нет поля — 1, умолчание не подставляется и digest политики не меняет), [review-protocol.md](review-protocol.md) |
112
114
  | `budgets{work, group, total, onUnknown}`, `prices[]` | Пределы USD и/или времени; тарифы |
113
115
 
@@ -613,6 +615,51 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
613
615
  закреплён, `impact` может нести только ссылку на базовую проверку
614
616
  (`baseline`), выбранную хостом для режима `affected`.
615
617
 
618
+ ### Зависшие попытки
619
+
620
+ Controller, ведущий очередь, раз в `stallSweep.intervalMs` (не меньше 1000 мс
621
+ и не больше `quietMs`) обходит исполняющиеся попытки. Движение попытки —
622
+ начало и конец её команды (вызов агента, gate, шаг среды, прочие команды),
623
+ вывод в stdout/stderr, граница стадии (`attempt.stage`) и прирост
624
+ процессорного времени дерева процессов исполняющихся команд (сумма
625
+ положительных приростов по каждому процессу, новый — от нуля) не меньше 1 %
626
+ прошедшего времени. Смена состава дерева сама движением не считается: цикл
627
+ ожидания (`until nc -z db 5432; do sleep 1; done`) рождает процессы, не
628
+ продвигаясь. Один `ps` на обход, общий для одновременных обходов; перерыв
629
+ от конца прошлого обхода дольше трёх интервалов (сон машины, занятый event
630
+ loop) начинает отсчёт заново, но не больше двух раз подряд.
631
+
632
+ Состояния: `active`; `quiet` — нет движения дольше `quietMs`; `stalled` —
633
+ дольше `stalledMs` (`quietMs < stalledMs`). Без данных `ps` о процессах
634
+ (отказ, Windows, нет времени процесса) оценка идёт только по выводу и не
635
+ поднимается выше `quiet` (`cpuUnavailable` в событии). Попытка без
636
+ исполняющейся команды (ждёт hook, ресурс, интеграцию) оценивается от последнего
637
+ движения с порогом `stalledMs` и тоже не выше `quiet`. Переход пишется в
638
+ `AttemptState.liveness` и событием `attempt.liveness` одной транзакцией под
639
+ fencing; само состояние между переходами не перезаписывается, а незаписанный
640
+ временным отказом переход повторяет следующий обход (не больше пяти раз;
641
+ отказ движка или схемы не повторяется). На `stalled` — снимок процессов
642
+ исполняющихся команд (pid, родитель, процессорное время, команда под маской
643
+ среды; команда без маски не сохраняется) и хвост вывода: в
644
+ `artifacts/<runId>/stall-<эпизод>.json` (один на эпизод, записывается первым) и в событии (≤ 20
645
+ процессов, ≤ 2000 символов). Дальше — `action`: `report` только сообщает
646
+ (попытка идёт до своего предела времени, движение вернёт `active`), `stop`
647
+ останавливает попытку отказом класса `stalled`: повтор или правка среды, а не
648
+ правка кода (`repairPolicy.stalled`, бюджет попыток он тратит, как `timeout`);
649
+ при `stop` зависшая попытка останавливается, даже если переход не записан.
650
+ Совместная проверка и gates на SHA вне попытки (`runGatesAt`) ведут свой
651
+ обход: переходы проверки — событие `joint.liveness` под её fencing, переходы
652
+ `runGatesAt` — `onLiveness` хоста и `liveness[]` результата (нагрузка как у
653
+ `attempt.liveness`, без файла снимка); при `stop` они останавливаются с
654
+ текстом зависания. `stallSweep` — надзор, а не условие
655
+ исполнения: в digest исполнения (основания попыток и reuse) он не входит.
656
+
657
+ `status` показывает `works[].liveness` (`quiet`/`stalled`) у активной попытки
658
+ без движения, `status --detail` — `detail.attempts[].liveness` (`state`,
659
+ `since`, `lastMovementAt`, `idleMs`, `activity`, `action`), `explain` —
660
+ причину `stalled` у работающего поручения: при `report` действует человек
661
+ (`fix-environment`), при `stop` — controller.
662
+
616
663
  ### RunEvent
617
664
 
618
665
  `{apiVersion, seq, at, type, graphId?, workId?, runId?, attempt?, payload}`.
@@ -634,6 +681,52 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
634
681
  под fencing: утративший владение не пишет ни замера, ни события. Повторное
635
682
  закрытие замера ничего не меняет и событий не создаёт.
636
683
 
684
+ `attempt.liveness` — переход живости попытки по обходу controller:
685
+ `{state, previous, lastMovementAt, idleMs, activity?: {kind:
686
+ 'agent'|'gate'|'step'|'command', label}, cpuUnavailable?, action?:
687
+ 'stop'|'report', snapshot?}`; `joint.liveness` — то же с `verificationId`; `action` и `snapshot` — только у `stalled` (см. «Зависшие
688
+ попытки»).
689
+
690
+ `work.retried` — поручение возвращено в очередь `engine.retry`: `{by:
691
+ 'operator'|'recovery'|'host', reset, spent?, reasonLength?}`. `by` — третий
692
+ аргумент `retry(workId, reset?, by?)`: CLI `retry` передаёт `operator`,
693
+ восстановление очереди (`repair`, эпизод по свойству) — `recovery`, хост без
694
+ актёра — `host` (по умолчанию). `reset` — сброс исчерпанного предела; `spent` —
695
+ засчитанные попытки до сброса (сброс обнуляет `WorkState.attempt`),
696
+ `reasonLength` — длина причины сброса; текста причины в событии нет. Повтор
697
+ без изменения (поручение уже в очереди) и отказ повтора событий не создают.
698
+
699
+ `work.cancelled` — поручение отменено: `{by: 'operator'|'host'|'graph',
700
+ hadAttempt}`. `engine.cancel(workId, reason?, by?)` (CLI `cancel` — `operator`,
701
+ по умолчанию `host`); `graph` — новая редакция графа убрала поручение.
702
+ `hadAttempt` — отменена и активная попытка: её `attempt.cancelled` идёт в той
703
+ же транзакции перед `work.cancelled`, у которого тогда те же `runId` и
704
+ `attempt`. Повторная отмена отменённого событий не создаёт.
705
+
706
+ `base.moved` — сдвиг ref базы `fencedRefMove(store, fence, timeoutMs?, by?)`:
707
+ `{by: 'operator'|'controller'|'host'}` (по умолчанию `host`), одно событие на
708
+ репозиторий, в той же транзакции, что проверка владения и `git update-ref`.
709
+ Отказ проверки или Git (CAS) отменяет и событие. `moveBase` без `move` событий
710
+ не пишет: у него нет хранилища.
711
+
712
+ `attempt.diagnosed` — причина отказа попытки: `{failureKind, cause, counted}`,
713
+ конверт несёт `graphId`, `workId`, `runId`, `attempt`. Пишется сразу за
714
+ `attempt.failed` (и `attempt.expired`) в той же транзакции под fencing.
715
+ `cause` (`environmentCauses`): `sandbox-launch`, `sandbox-network`,
716
+ `sandbox-filesystem`, `sandbox-policy`, `dependency-network` — ставит gate в
717
+ точке обнаружения (`TaskFailure.diagnosis`); `transport`, `preflight`
718
+ (`BlockedError` до работы), `provider-auth`, `provider-limit`, `stalled`,
719
+ `shutdown` (прерывание штатной остановкой), `lease-expired` — по классу отказа
720
+ и его признакам; `other` — отказ окружения без известной причины; `none` —
721
+ отказ не окружения. Хост, вызывающий `engine.fail`, может передать
722
+ `options.cause`; движок приводит её к классу (у отказа не окружения — всегда
723
+ `none`). `counted` — отказ засчитан в предел попыток (`maxAttempts`): не
724
+ засчитаны отказы до работы (`blocked`), окружения и провайдера, истёкшее
725
+ владение и прерывание остановкой; зависание (`stalled`) засчитано. Отчёт
726
+ считает попытки засчитанными по тому же правилу. Отказ до работы с классом
727
+ не окружения получает причину `preflight`. Текста отказа в событии
728
+ нет.
729
+
637
730
  `finished` может не прийти: поздний finish владельца, утратившего срок,
638
731
  отклоняется (runner его не повторяет), упавший процесс его не пишет, а `adopt`
639
732
  и recovery открытые замеры прежнего владельца не закрывают. Такая стадия
@@ -673,7 +766,7 @@ original}` (исходный тип, не длиннее 200 символов;
673
766
  (`joint.started`, `joint.finished`). `config.started`, `config.reconfigure-*`
674
767
  и `config.reconfigured` меняют применённую политику и запрос операции
675
768
  (`policy.applied`, `policy.reconfigure`). `base.moved` — проверка владения
676
- операцией и CAS-сдвиг ref базы; записей и событий не создаёт.
769
+ операцией и CAS-сдвиг ref базы; записей не создаёт, событие — `base.moved`.
677
770
 
678
771
  ### ValueReport
679
772
 
@@ -696,7 +789,14 @@ original}` (исходный тип, не длиннее 200 символов;
696
789
  внешних ссылок (CSP `default-src 'none'; style-src 'unsafe-inline'; img-src
697
790
  data:`), светлая и тёмная схема по `prefers-color-scheme`, таблицы
698
791
  прокручиваются на ширине телефона, столбики недель (inline SVG) — от 3
699
- активных недель. Модуль `devcontour-harness/report` без `node:*` и без zod.
792
+ активных недель. Модуль `devcontour-harness/report` без `node:*` и без zod. Запись
793
+ файла отчёта (`report --out`) — `writeReportFile(out, stateDir, text)` из
794
+ корня пакета (не из `./report`: она использует `node:fs`): текст пишется во
795
+ временный файл каталога цели и переименовывается поверх цели, без записи
796
+ сквозь symlink и жёсткие ссылки; цель внутри каталога состояния, symlink,
797
+ не обычный файл или файл с `nlink > 1` — `PATH_CONFLICT`, недоступный
798
+ каталог — `INVALID_INPUT`; права прежнего файла сохраняются, новый —
799
+ `REPORT_FILE_MODE` (`0600`).
700
800
 
701
801
  **Детерминизм.** Тот же вход и параметры — те же байты JSON, Markdown и HTML
702
802
  при любом порядке входных массивов, часах и часовом поясе. `asOf` по
@@ -750,15 +850,48 @@ lower`). `firstPassRaw` — попытка вообще одна.
750
850
  иначе `lower` («≥»); без единой известной цены при неизвестных —
751
851
  `unknown` (`value: null`), не `$0`. Расход отклонённых попыток
752
852
  (`cost.rejected`) и расход отказов окружения (`environment.neutral`) —
753
- одна и та же атрибуция по всем завершённым попыткам окна.
853
+ одна и та же атрибуция по всем завершённым попыткам окна. `environment.neutral`
854
+ — вся корзина `environment`, включая зависания (`stalled`), хотя они
855
+ засчитаны в предел попыток.
856
+ - Пробел записи определяется по порядку журнала (`seq`), а не по времени:
857
+ `at` события — часы записи, время попытки — часы движка.
754
858
  - Действия человека — только записи с актёром-человеком: решения recovery
755
- с источником `operator`. Удержания (`work.held`) и отмены попыток актёра
756
- не называют (удерживают и операции хоста, например смена контракта): они
757
- показаны отдельно (`holds`, `cancelledAttempts`) и в действия человека не
758
- входят. Повторы, сбросы, отмена без попытки и сдвиг базы пока не
759
- записываются: `withAction` — нижняя граница, «без действий человека»
760
- (`withoutAction`) пока не измеримо (`value: null`, `bound: unknown`),
761
- `retries`/`resets`/`baseMoves` — `null`.
859
+ с источником `operator`, повторы и отмены с `by: operator` (`work.retried`,
860
+ `work.cancelled`). Удержания (`work.held`) актёра не называют (удерживают и
861
+ операции хоста, например смена контракта): они показаны отдельно (`holds`)
862
+ и в действия человека не входят; так же `cancelledAttempts` — отменённые
863
+ попытки по записям попыток. Повторы восстановлением (`recovery`), сдвиги
864
+ базы controller и отмены новой редакцией графа — автоматические.
865
+ - Вмешательства по событиям (`actions.recorded`): числа в окне по актёрам —
866
+ повторы, сбросы, отмены (и отмены без активной попытки), сдвиги базы.
867
+ Запись начинается с первого события версии, которая их пишет
868
+ (`work.retried`, `work.cancelled`, `base.moved`, `attempt.diagnosed`;
869
+ `recorded.from`); раньше него действие могло быть, но не записано. Нет ни
870
+ одного такого события в журнале — `recorded: null`, `withAction` — нижняя
871
+ граница, «без действий человека» (`withoutAction`) не измеримо (`value:
872
+ null`, `bound: unknown`). С записью: `recorded.bound: lower`, если в окне
873
+ есть попытки, события или принятые поручения раньше `from` или пробел записи
874
+ (`gaps`: новая попытка после отказа или отмены без `work.retried` и без новой
875
+ редакции графа между ними — работала версия без этих событий, например
876
+ после отката и повторного обновления), иначе `exact`. Пробел, не оставивший
877
+ такой попытки, не обнаруживается — это постоянное ограничение. Суммы
878
+ `retries`/`resets` — только при `bound: exact`, иначе `null` (числа по
879
+ актёрам с границей — в `recorded`). Сдвиги базы — всегда нижняя граница
880
+ (`baseMovesBound: lower`, сумма `baseMoves` всегда `null`): перенос вне
881
+ `fencedRefMove` (`moveBase` без `move`) не пишется; к поручениям они не
882
+ относятся.
883
+ - Поручение «без действий человека» известно, если оно начато не раньше
884
+ `from` (начало — согласование первой попытки `wait.approvedAt`, иначе
885
+ `WorkState.approvedAt`, иначе начало первой попытки), без пробела записи,
886
+ и у него нет действий без актёра: повтора или отмены хостом (`host`) и
887
+ удержания (`work.held` — его ставят и человек, и операции хоста). Прочие
888
+ принятые без действия оператора идут в `unknown` обеих мер (`bound:
889
+ lower`).
890
+ - Подпричины окружения (`environment.causes`): отказы окружения окна по
891
+ `attempt.diagnosed` своей попытки — строки `{cause, count, counted}` (по
892
+ убыванию числа); отказ без события (записан раньше) — `undiagnosed`, тогда
893
+ `bound: lower`. Нет ни одного `attempt.diagnosed` в журнале — `causes:
894
+ null`.
762
895
  - Отказы окружения (`environment.share`) — среди классифицированных; если
763
896
  есть отказы только в gates подготовки (`setupCheckFailures`), доля —
764
897
  нижняя граница («at least», «M more may be environment»).
@@ -789,6 +922,120 @@ prompt, вывода runtime, текстов находок, ошибок и п
789
922
  недели без активности — `gap`), 50 строк gates и стадий; JSON ≤ 512 КБ,
790
923
  HTML ≤ 1 МБ. Усечение отмечено флагом и ограничением.
791
924
 
925
+ ### HandoffPack
926
+
927
+ Пакет передачи контекста (`harness handoff`, `handoffPack(source, options)`
928
+ и `handoffMarkdown(pack)` из корня пакета; `handoffVersion: 1`,
929
+ `handoffPackSchema`, `schemas/handoff-pack.schema.json`). Ведущий агент хоста,
930
+ который ведёт доску через много попыток, начинает новую сессию с пакета, а не
931
+ с пересказа предыдущей: факты собираются из хранилища теми же проекциями, что
932
+ `status --detail` и `explain`, и только читают состояние.
933
+
934
+ - `summary`, `limits` — счёт поручений по статусам, `maxAttempts` и
935
+ `repairBudget` политики;
936
+ - `queue`, `controller` — пауза выдачи, её причина и кто её снимает
937
+ (`queueStop`, `queuePause`), операция, держащая паузу (`operation`), и
938
+ классы отказа паузы runtime (`failures`); держатель роли controller и
939
+ свежесть срока;
940
+ - `active` — идущие попытки: стадия и её длительность, heartbeat, gates
941
+ текущей фазы (`attemptView`); `unfinished` — незакрытые записи попыток с
942
+ истёкшим владением или такие, которые поручение уже не ведёт;
943
+ - `works` — открытые поручения (идущие, упавшие, план, остальные): класс и
944
+ причина провала, удержание, эпизод восстановления с предложением,
945
+ блокировки (без общей паузы очереди; сверх предела — `blockersTruncated`) и
946
+ `next` — кто и что делает (по диагнозу `explain`; стадия и свойство — по
947
+ `nextAction`);
948
+ - `stops` — диагнозы `explain` без проб runtime, кроме `action: none`.
949
+ Отменённая работа (и упавшая с классом `cancelled`) — остановка
950
+ (`CANCELLED`, lead `replan-dependents`), только пока от неё прямо зависит
951
+ незавершённая работа (не `done` и не `cancelled`); ждущую через
952
+ отменённую же промежуточную ведёт диагноз той. Без таких работ у
953
+ отменённой действия нет (`action: none`): в общий `explain` и пакет она не
954
+ входит, explain этой работы (`--work`) её показывает. Упавшая отменой
955
+ открыта, а движок её не повторяет: без ждущих — решение человека (user
956
+ `user-decision`: `harness retry` или отмена), шаг `nextAction` —
957
+ `cancelled`. Любая отмена в группе останавливает её автоматическое
958
+ восстановление: диагноз упавшей сестры называет отменённую работу.
959
+ Остановка выдачи общей паузой очереди — одна запись с `queue: true` без
960
+ `workId`; одинаковые остановки на выдаче у разных поручений тоже
961
+ свёрнуты; `works` — первые 20 затронутых, `worksCount` — сколько всего.
962
+ Решения (`actor` lead или user и действие не `wait`) идут первыми;
963
+ - `failures` — последние провалившиеся и истёкшие попытки, новые первыми:
964
+ `failureKind`, код (`stopCodeOf`), текст ошибки и текущий статус
965
+ поручения (`workStatus`);
966
+ - `budgets` — общий бюджет и бюджеты групп (с `--graph` — только его
967
+ группа), бюджеты поручений — только с расходом или не в пределах и со
968
+ своими вызовами (попытки, вызовы о поручении). Вызов о группе (ревью и
969
+ проверка плана) засчитывается целиком бюджету каждого её открытого
970
+ поручения (так действует ограничение поручения), но в строках группы и
971
+ `total` — один раз; поручение, весь расход которого — такие вызовы, не
972
+ перечисляется (`truncated.budgetsShared`), если только его строка не
973
+ держит выдачу (превышена или не определена при `onUnknown: stop`): тогда
974
+ она показана как ограничение поручения. Строка бюджета:
975
+ сообщено (`reportedUsd`) и оценено (`estimatedUsd`) против предела, время,
976
+ `complete` и причины неполноты (вызовы без стоимости, незавершённые,
977
+ брошенные, попытки без учёта); при неполном расходе сумма — нижняя граница
978
+ («≥ $X (неполно: …)» в Markdown), остаток — `null`. `repairs` —
979
+ восстановления незавершённых заданий графов;
980
+ - `next` — следующий шаг доски: первое решение; иначе идущая попытка со
981
+ свежим сроком владения — ждать (без controller — до `leaseUntil`); попытка
982
+ с истёкшим сроком или очередь без controller — `command: "harness run"` (run истечёт брошенную
983
+ попытку и продолжит очередь); пауза оператора — `"harness resume"`; иначе
984
+ первый открытый шаг поручения;
985
+ - `intentions` — единственный текст не из хранилища: намерения агента.
986
+
987
+ Пределы (`HANDOFF_LIMITS`): 50 открытых поручений, 30 остановок (после
988
+ свёртки) с 5 ссылками evidence каждая, 10 провалов, 20 незавершённых
989
+ попыток, 3 блокировки на поручение, 20 строк бюджетов, 10 заданий, 20
990
+ намерений по 1000 знаков. Тексты из хранилища и намерения очищаются от
991
+ escape-последовательностей терминала (ANSI CSI, OSC), серия управляющих
992
+ символов заменяется пробелом; строки фактов усечены до 300 знаков, имена и
993
+ идентификаторы — до 200, с «…» и без разрыва суррогатной пары. Пакет не
994
+ больше `HANDOFF_MAX_BYTES` (256 КБ UTF-8): сверх него записи отбрасываются в
995
+ порядке «намерения с конца, старые провалы, поручения без решения,
996
+ остановки без решения, незавершённые попытки, остальные поручения и
997
+ остановки, строки бюджетов» (`truncated.bySize`), отказа по размеру нет.
998
+ Сколько записей каждого списка не вошло — `truncated`; бюджеты поручений в
999
+ пределах и без расхода не показываются намеренно и считаются отдельно
1000
+ (`budgetsWithin`), как и бюджеты поручений только с расходом вызовов о
1001
+ группе (`budgetsShared`), усечённые и отброшенные намерения — `intentions` и
1002
+ `intentionsDropped`. Тексты из хранилища маскируются по значениям секретов
1003
+ политики из окружения читающего процесса (`policySecrets`, как у
1004
+ коннектора): секрет, которого в этом окружении нет, маска не знает —
1005
+ библиотеке можно передать свою `redact`. Fencing-токены в пакет не
1006
+ попадают.
1007
+
1008
+ **Хост.** Источник пакета — `HandoffSource`: `{ engine, policy, workflows }`,
1009
+ где `engine` — `Engine` над хранилищем хоста, `policy` — его
1010
+ `ExecutionPolicy`, `workflows` — `list()` заданий (пакет и диагнозы берут
1011
+ задания `kind: "graph"`) и `continues(job, view, { reconfigureApplies })`,
1012
+ продолжит ли очередь задание сама. `Harness` удовлетворяет типу структурно;
1013
+ хост со своим движком передаёт свой адаптер заданий без экземпляра
1014
+ `Harness`. Состояние доски над тем же источником — `statusOf(source,
1015
+ graphId?, { detail })` (`Harness.status` — та же функция).
1016
+
1017
+ Параметры `handoffPack`: `graphId`, `intentions`, `redact`, а также
1018
+ `maxBytes` — предел хоста в байтах UTF-8, целое от `HANDOFF_MIN_BYTES`
1019
+ (4 КБ) до `HANDOFF_MAX_BYTES` (по умолчанию), иначе `INVALID_INPUT`; порядок
1020
+ отбрасывания и счётчики `truncated` те же, что у предела по умолчанию, а
1021
+ `bySize` значит «записи отброшены ради предела», а не «пакет уложился».
1022
+ Сводка, очередь, идущие попытки, задания и `next` не отбрасываются, поэтому
1023
+ уложиться не гарантируется: размер результата хост проверяет сам.
1024
+ `HANDOFF_MIN_BYTES` — нижняя граница, ниже которой не помещается даже обычный
1025
+ минимальный пакет, а не гарантия. `measure` — что укладывается в предел: `json` (по умолчанию) —
1026
+ сериализованный пакет; `markdown` — и JSON, и `handoffMarkdown(pack)`
1027
+ (Markdown бывает длиннее JSON: «|» в ячейке экранируется). Свой раздел
1028
+ Markdown хост учитывает, уменьшая `maxBytes`. Маску из секретов политики и
1029
+ своих значений хост составляет из `policySecrets(policy, env?)`,
1030
+ `redactor` и `composeRedactors` корня пакета.
1031
+
1032
+ Весь пакет — один снимок хранилища: `handoffPack` выполняет status,
1033
+ диагнозы и чтение заданий графов внутри одного `read`
1034
+ (`SqliteExecutionStore.read` вложенным чтением использует снимок внешнего,
1035
+ без второго `BEGIN`). Попытка со свежим сроком владения без живого
1036
+ controller — `next` «ждать до `leaseUntil` или проверить процесс-владелец»
1037
+ без команды; `harness run` называется только для попытки с истёкшим сроком.
1038
+
792
1039
  ## Порты
793
1040
 
794
1041
  | Порт | Договор |
@@ -942,6 +1189,7 @@ stdout — один JSON `CliEnvelope`: `{apiVersion, command, ok: true, data}`
942
1189
  | `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]` | да | план файлов, `created`, `manifest`, `facts`, `toolchain`, `next` | Create-only `.harness/`, manifest до политики, политика последней; повтор — `created: []`; иное решение — `PATH_CONFLICT` |
943
1190
  | `explain` | `--state D --policy F [--work ID]` | нет | `diagnoses[]` (`StopDiagnosis`) | Только чтение: без повторов, вызовов моделей и изменений состояния |
944
1191
  | `report` | `--state D [--since T\|Nd\|Nw] [--until T] [--as-of T] [--format json\|md\|html] [--no-titles] [--out F]` | нет | `ValueReport`; с `--out` — `{out, format, bytes, asOf}` | Только чтение; те же данные и параметры — те же байты |
1192
+ | `handoff` | `--state D [--graph ID] [--intent T]… [--format json\|md]` | нет | `HandoffPack`; с `--format md` — Markdown без конверта | Только чтение; агент добавляет только намерения |
945
1193
  | `plan-request` | `--brief F --policy F [--context F] [--contracts D] [--requirements [R:]F]… [--human]` | нет | `prompt`, `readOnly`, `recommendedTasks`, `maxTasks`, `basis`, `facts` (`PlanningFacts`) | Чистая функция входов: та же постановка и те же факты — тот же prompt и `basis`; модель не вызывается |
946
1194
  | `plan-check` | `--draft F --policy F [--context F] [--contracts D] [--brief F [--basis H]]` | нет | `issues`, `checkPlan`; без проблем — `graph`, `graphDigest`, `basis` | Чистая функция входов и `HEAD` источников требований; согласования не выдаёт, gates не запускает; расхождение `--basis` — `APPROVAL_STALE` |
947
1195
  | `capabilities` | — | нет | каталог общих операций (`OperationCatalog`) | Чистая функция установленной версии пакета |
@@ -974,10 +1222,20 @@ md|html` — документированное исключение, как `--
974
1222
  `INVALID_INPUT`; stdout — конверт `{out, format, bytes, asOf}`. Неверное
975
1223
  окно (`--since` не раньше `--until`, время без пояса) — `INVALID_INPUT`;
976
1224
  нет каталога — `NOT_FOUND`, каталог не создаётся. Флаги `--since`,
977
- `--until`, `--as-of`, `--format`, `--no-titles` принимает только `report`.
1225
+ `--until`, `--as-of`, `--no-titles` принимает только `report` (`--format` — ещё
1226
+ `handoff`, со значениями json и md).
978
1227
  Пределы размера (JSON 512 КБ, HTML и Markdown 1 МБ) проверяют сами
979
1228
  `valueReport` и рендеры (`assertReportBytes`, `INTERNAL`).
980
1229
 
1230
+ **`handoff`.** Открывает каталог состояния только для чтения (политика — из
1231
+ `binding.json`, как у `status`) и строит `HandoffPack`. `--format json` (по
1232
+ умолчанию) — обычный конверт; `--format md` — документированное исключение,
1233
+ как у `report`: успешный ответ печатается Markdown без конверта. Отказ —
1234
+ JSON-конверт в обоих режимах; нет каталога — `NOT_FOUND`, каталог не
1235
+ создаётся; неизвестный `--graph` — `NOT_FOUND`; больше 20 `--intent` или
1236
+ `--format` не json/md — `INVALID_INPUT`. `--intent` принимает только
1237
+ `handoff`, `--format` — `report` и `handoff`.
1238
+
981
1239
  **Причина отказа окружения `dependency-network`.** Установка зависимостей,
982
1240
  упавшая на сети или реестре пакетов, получает класс `environment`, а не `gate`
983
1241
  (правило — [архитектура](architecture.md#что-гарантируется), «Сеть и реестр при установке зависимостей»). Отдельного поля