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

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 (125) hide show
  1. package/README.md +22 -2
  2. package/docs/contracts.md +309 -35
  3. package/docs/release-notes/0.1.0-alpha.35.md +27 -0
  4. package/docs/release-notes/0.1.0-alpha.36.md +26 -0
  5. package/docs/release-notes/0.1.0-alpha.37.md +40 -0
  6. package/docs/standalone.md +20 -0
  7. package/docs/toolchains.md +57 -2
  8. package/docs/upgrade.md +143 -0
  9. package/lib/agents/cli-adapter.d.ts +10 -1
  10. package/lib/agents/cli-adapter.js +38 -7
  11. package/lib/agents/schemas.d.ts +84 -2
  12. package/lib/agents/schemas.js +49 -1
  13. package/lib/agents/usage.d.ts +9 -0
  14. package/lib/agents/usage.js +22 -1
  15. package/lib/cli.js +149 -1
  16. package/lib/contracts/cli.d.ts +1544 -171
  17. package/lib/contracts/cli.js +233 -2
  18. package/lib/contracts/diagnosis.d.ts +10 -4
  19. package/lib/contracts/diagnosis.js +4 -0
  20. package/lib/contracts/errors.d.ts +9 -1
  21. package/lib/contracts/errors.js +8 -0
  22. package/lib/contracts/events.d.ts +468 -60
  23. package/lib/contracts/events.js +79 -0
  24. package/lib/contracts/execution.d.ts +301 -50
  25. package/lib/contracts/execution.js +60 -0
  26. package/lib/contracts/failure.d.ts +20 -3
  27. package/lib/contracts/failure.js +14 -2
  28. package/lib/contracts/handoff.d.ts +79 -20
  29. package/lib/contracts/handoff.js +42 -1
  30. package/lib/contracts/index.d.ts +1 -0
  31. package/lib/contracts/index.js +1 -0
  32. package/lib/contracts/input-state.d.ts +13 -0
  33. package/lib/contracts/input-state.js +32 -0
  34. package/lib/contracts/input.d.ts +442 -0
  35. package/lib/contracts/input.js +321 -0
  36. package/lib/contracts/planning.d.ts +4 -0
  37. package/lib/contracts/policy.d.ts +17 -2
  38. package/lib/contracts/policy.js +31 -2
  39. package/lib/contracts/ports.d.ts +64 -2
  40. package/lib/contracts/project.d.ts +127 -0
  41. package/lib/contracts/project.js +99 -0
  42. package/lib/contracts/published.d.ts +631 -92
  43. package/lib/contracts/published.js +4 -1
  44. package/lib/contracts/repair-policy.d.ts +30 -1
  45. package/lib/contracts/repair-policy.js +52 -0
  46. package/lib/contracts/report.d.ts +55 -21
  47. package/lib/contracts/report.js +33 -2
  48. package/lib/contracts/result.d.ts +28 -24
  49. package/lib/contracts/review.d.ts +47 -8
  50. package/lib/contracts/review.js +21 -1
  51. package/lib/control/harness.d.ts +2555 -51
  52. package/lib/control/harness.js +112 -6
  53. package/lib/control/recovery.d.ts +2 -2
  54. package/lib/control/report.js +1 -0
  55. package/lib/control/status.d.ts +30 -22
  56. package/lib/control/status.js +11 -1
  57. package/lib/control/workflow.d.ts +8 -8
  58. package/lib/engine/budget.d.ts +86 -3
  59. package/lib/engine/budget.js +45 -10
  60. package/lib/engine/classify.js +1 -1
  61. package/lib/engine/engine.d.ts +3091 -83
  62. package/lib/engine/engine.js +1209 -101
  63. package/lib/engine/failure.d.ts +1 -1
  64. package/lib/engine/failure.js +1 -1
  65. package/lib/engine/input-policy.d.ts +68 -0
  66. package/lib/engine/input-policy.js +285 -0
  67. package/lib/engine/input-requests.d.ts +64 -0
  68. package/lib/engine/input-requests.js +187 -0
  69. package/lib/engine/measured.d.ts +6 -1
  70. package/lib/engine/measured.js +12 -1
  71. package/lib/engine/prompt.d.ts +4 -2
  72. package/lib/engine/prompt.js +13 -1
  73. package/lib/engine/property-recovery.js +4 -0
  74. package/lib/engine/repair.d.ts +2 -0
  75. package/lib/engine/repair.js +13 -4
  76. package/lib/engine/reuse.js +2 -0
  77. package/lib/engine/runner.d.ts +33 -4
  78. package/lib/engine/runner.js +275 -23
  79. package/lib/environment/lifecycle.d.ts +8 -0
  80. package/lib/environment/lifecycle.js +15 -2
  81. package/lib/explain/state.d.ts +16 -2
  82. package/lib/explain/state.js +262 -79
  83. package/lib/handoff/markdown.js +10 -0
  84. package/lib/handoff/pack.js +42 -1
  85. package/lib/index.d.ts +11 -1
  86. package/lib/index.js +11 -1
  87. package/lib/init/inspect.d.ts +34 -0
  88. package/lib/init/inspect.js +292 -0
  89. package/lib/init/project.js +14 -31
  90. package/lib/integrations/connector/commands.d.ts +12 -12
  91. package/lib/integrations/connector/config.d.ts +4 -4
  92. package/lib/integrations/connector/delivery.d.ts +1 -1
  93. package/lib/integrations/relay-v2/protocol.d.ts +4 -4
  94. package/lib/profiles/resolve.d.ts +2 -1
  95. package/lib/projections/enums.d.ts +1 -1
  96. package/lib/projections/enums.js +4 -0
  97. package/lib/projections/index.d.ts +1 -0
  98. package/lib/projections/index.js +1 -0
  99. package/lib/projections/input.d.ts +17 -0
  100. package/lib/projections/input.js +28 -0
  101. package/lib/projections/stop.d.ts +42 -1
  102. package/lib/projections/stop.js +117 -6
  103. package/lib/report/compute.d.ts +4 -1
  104. package/lib/report/compute.js +26 -0
  105. package/lib/report/document.js +2 -1
  106. package/lib/storage/document.d.ts +68 -28
  107. package/lib/testing/index.d.ts +1 -1
  108. package/lib/testing/index.js +1 -1
  109. package/lib/testing/store-contract.d.ts +8 -1
  110. package/lib/testing/store-contract.js +194 -1
  111. package/lib/verification/confirm.d.ts +3 -3
  112. package/lib/verification/corpus.d.ts +9 -9
  113. package/lib/verification/gates.d.ts +119 -0
  114. package/lib/verification/gates.js +311 -4
  115. package/package.json +1 -1
  116. package/schemas/execution-document.schema.json +141 -0
  117. package/schemas/execution-policy.schema.json +26 -0
  118. package/schemas/handoff-pack.schema.json +155 -4
  119. package/schemas/input-request.schema.json +665 -0
  120. package/schemas/project-facts.schema.json +393 -0
  121. package/schemas/result-envelope.schema.json +2 -0
  122. package/schemas/run-event.schema.json +628 -0
  123. package/schemas/run-result.schema.json +2 -0
  124. package/schemas/stop-diagnosis.schema.json +7 -1
  125. package/schemas/value-report.schema.json +79 -7
@@ -0,0 +1,40 @@
1
+ # devcontour-harness 0.1.0-alpha.37
2
+
3
+ Вопрос исполнителя: writer останавливается на развилке, ответ проходит ревью
4
+ контекста и применяется к следующей попытке. Диагностика остановок для многих
5
+ работ за одно чтение. `stateVersion` и `policyVersion` прежние.
6
+
7
+ ## Изменения
8
+
9
+ - **Вопрос исполнителя.** Необязательные `inputRequest` и `assumptions` в
10
+ ответе writer, политика `inputPolicy {threshold 1–11, criticalPaths}`
11
+ (порог по умолчанию 7, 11 — автономный режим), локальное пространство
12
+ `input-requests`, класс отказа `needs-input` и код `INPUT_REQUIRED`.
13
+ Ответ, снимок контекста с ответом, его ревью, применение, замена и перенос
14
+ ответа в новую редакцию; команды CLI `input-*`; необязательный порт
15
+ `ExecutionHost.input`. Подробно — `docs/contracts.md#вопрос-исполнителя`.
16
+ - **Диагностика многих работ.** `stopInputsOf(source, { maxAttempts,
17
+ repairBudget, workIds })`: каждая работа из `workIds` получает то же, что
18
+ вызов с её `workId`, в порядке состояния; неизвестный ID — `NOT_FOUND`,
19
+ `workId` вместе с `workIds` — `INVALID_INPUT`. Вызов для всей доски и для
20
+ набора читает общие данные один раз и линеен по числу работ и связей.
21
+ - **Помощники движка** (каждый действителен только внутри своего чтения):
22
+ `Engine.approvalStaleness(view)`, `Engine.budgetBlockers(view)`,
23
+ `Engine.budgetBlocksOf(workIds | undefined, view)` — блокировки бюджета
24
+ набора работ за одно чтение, значение равно `budgetBlockOf(workId, view)`.
25
+ Необязательные `records` у `budgetBlockOf` и `blocking` у `repairDecision`.
26
+ - **Перенос ответа.** Снятие устаревшего перенесённого ответа сохраняет
27
+ запись замены в `closed.previous`.
28
+ - **Объяснение.** Работа, отказавшая до старта (не засчитанная попытка,
29
+ например без закреплённого снимка контекста), объясняется фазой `preflight`;
30
+ `StopInput.work.preflight` — новое поле. Класс отказа `needs-lead` и его
31
+ правила прежние.
32
+ - **Отчёт.** `report.inputs.carryStale` считает вопросы с устаревшим
33
+ перенесённым ответом; `report.inputs.closed` их больше не считает.
34
+
35
+ ## Обновление
36
+
37
+ Новое аддитивно; схемы прежних версий не принимают новые необязательные поля
38
+ (`inputPolicy`, `closed.previous`, `inputs.carryStale`): при откате уберите
39
+ их или восстановите копию каталога состояния, снятую до обновления.
40
+ Подробнее — `docs/upgrade.md`.
@@ -109,6 +109,26 @@ realpath корня, поэтому повтор и новая сессия на
109
109
  дописывает недостающее; `status: complete` — только при валидных manifest и
110
110
  политике.
111
111
 
112
+ ## Факты репозитория без записи
113
+
114
+ `inspectProject({ repository })` из корня пакета — библиотечная инспекция до
115
+ любой подготовки (схема `project-facts`): Git-корень, вид worktree, base SHA,
116
+ ветка, незакоммиченные изменения, их число (`changeCount`) и первые 50 путей; lockfiles корня и менеджер пакетов
117
+ (`detected`, `ambiguous`, `none`) с полем `packageManager`; подходящие
118
+ встроенные профили с digest; scripts корневого `package.json` и похожие на
119
+ проверки (`checks`); версии git, node и менеджера с требуемой версией и её
120
+ источником; наличие CLI `claude`/`codex` — `available`, `missing` или
121
+ `version-error`, авторизация всегда `unknown`. `diagnostics` — коды с
122
+ `severity` (`blocker`, `warning`, `info`), текстом и следующим действием;
123
+ `ready` — нет блокирующих.
124
+
125
+ Инспекция ничего не создаёт (`.harness`, state, refs, индекс Git), не
126
+ исполняет scripts манифестов и не вызывает модели: единственные процессы —
127
+ Git без optional locks и пробы `--version` во временном каталоге. Маркеры
128
+ DevContour и готовый `.harness/` — факты (`info`), а не отказ. `init`
129
+ определяет корень и профиль тем же алгоритмом; хост применяет к фактам свои
130
+ правила размещения.
131
+
112
132
  ## Планирование
113
133
 
114
134
  План составляет сам ведущий агент: отдельная модель-планировщик не
@@ -158,8 +158,8 @@ Isolation `os` пишет только в worktree и временный кат
158
158
  скачивает через прокси песочницы.
159
159
 
160
160
  Исполнитель и проверки ревьюера переменную `npm_config_store_dir` не получают: их окружение строится
161
- отдельно. Установка исполнителя до первого gate поэтому на seed не опирается и идёт как без
162
- хранилища.
161
+ отдельно. Зависимости в дерево исполнителя ставит controller до его работы
162
+ ([ниже](#зависимости-исполнителя)) — в окружении фазы, то есть уже с хранилищем.
163
163
 
164
164
  | Исход | Что происходит |
165
165
  | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -208,6 +208,61 @@ Isolation `os` пишет только в worktree и временный кат
208
208
  `dependency-store.json` в её артефактах. Другие менеджеры добавляются записью в таблице `managers`
209
209
  (`verification/dependency-store.ts`); пока поддержан только pnpm.
210
210
 
211
+ ## Зависимости исполнителя
212
+
213
+ Песочница Claude Code закрывает запись в `**/.idea` и `**/.vscode` от рабочего каталога исполнителя
214
+ без возможности снять запрет настройками, а у codex по умолчанию нет сети: установка пакетов
215
+ самим исполнителем не проходит, и до сдачи работы он не может собрать проект и запустить тесты.
216
+ Поэтому перед исполнителем controller сам исполняет в его дереве **gates установки** попытки —
217
+ обязательные gates, чей argv однозначно установка известным менеджером (`npm ci|install`,
218
+ `pnpm install|fetch`, `yarn`; скрипты, `npx` и shell не подходят), в их порядке:
219
+
220
+ - после `prepare`, хранилища зависимостей и наложения черновика прежней попытки (манифесты, которые
221
+ он меняет, ставятся сразу), до снимка защищённых путей исполнителя и его вызова. `dependsOn` gate
222
+ установки не исполняется: проверки, от которых он зависит, остаются gates кандидата. Если
223
+ установка есть ещё и в `prepare`, менеджер запустится дважды; второй раз обычно ничего не делает;
224
+ - под той же изоляцией, что и gate, при любом `isolation.mode`: в `os` — песочница проверки с
225
+ записью только в дерево, сетью `isolation.domains` и сверкой защищённых путей; в `none` — без
226
+ песочницы, так же, как исполняются сами gates (выбор `none` уже разрешает gates работать на хосте);
227
+ в окружении фазы, с `timeoutMs` gate;
228
+ - **evidence не пишется**: настоящий gate установки по-прежнему исполняется на SHA кандидата после
229
+ сдачи работы и остаётся единственным свидетельством.
230
+
231
+ Следы установки исполнителю не вменяются и в его коммит не попадают (он коммитит дерево целиком):
232
+
233
+ - каждый новый каталог `node_modules` — в корне, в пакетах workspace и внутри каталогов, уже бывших
234
+ неотслеживаемыми (например, созданных `prepare`), — скрывается от git собственным `.gitignore`, как
235
+ копия хранилища. Поиск — обход дерева без перехода по ссылкам, без спуска в `node_modules` и с
236
+ пределом в 200 000 элементов; недоделанный обход назван в квитанции (`incomplete`);
237
+ - прочие неотслеживаемые и не игнорируемые пути, которых до установки не было (сборка `dist/`,
238
+ сгенерированный код, журналы менеджера), удаляются; пустые каталоги остаются (git их не видит).
239
+ Пути, бывшие до установки, и содержимое прежних `node_modules` не трогаются; вложенный репозиторий
240
+ не удаляется и называется в `kept`;
241
+ - отслеживаемые файлы (lockfile, манифест), которые установка изменила, возвращаются к прежним байтам —
242
+ базы или наложенного черновика, — HEAD к базе; это считается отказом установки.
243
+
244
+ Заметка исполнителю при успехе: зависимости поставлены controller, установку не запускать. Фраза о
245
+ том, что lockfiles и манифесты менять нельзя, добавляется, только если все манифесты и lockfiles в
246
+ каталогах установки лежат в `protectedPaths`. Убранные пути названы числом и первыми именами. Отказ
247
+ (код выхода, сеть, timeout) попытку не роняет: исполнитель получает заметку «Dependencies were not
248
+ installed before your turn (gate "…")», в которой сводка вывода (не больше 400 символов) приведена
249
+ строкой JSON и помечена как недоверенный вывод инструмента, а не указания; стадия
250
+ `writer-dependencies` в `timings` закрывается исходом `failed`. Исключение — защищённый путь
251
+ (конфигурация IDE, shell, git или Claude), созданный или изменённый установкой: над деревом базы это
252
+ отказ среды `environment` с причиной `sandbox-policy`, над наложенным черновиком (манифесты писал
253
+ прежний исполнитель) — `scope-violation`, как у gate кандидата. Взятый кандидат прежней попытки
254
+ исполнителя не вызывает, и установки до него нет. Журналы и квитанция `writer-dependencies.json`
255
+ (`installed`, `failed`, `frozen`, `sealed`, `removed`, `removedCount`, `kept`, `incomplete`) — в
256
+ `artifacts/<попытка>/candidate/writer-dependencies/`.
257
+
258
+ Gate установки кандидата исполняется в том же дереве и переиспользует его `node_modules`, которые
259
+ исполнитель мог изменить: `pnpm install --frozen-lockfile` сверяет lockfile, но не содержимое уже
260
+ установленных пакетов. Integration исполняется в новом checkout с чистой установкой; именно она
261
+ подтверждает, что результат собирается из lockfile.
262
+
263
+ Выключить: `"writerDependencies": false` в репозитории политики. Без поля — включено, digest
264
+ политики прежний.
265
+
211
266
  ## Диагностика: doctor и preflight
212
267
 
213
268
  `harness doctor --policy policy.json` (или `--state`) добавляет `toolchains[]` — по
package/docs/upgrade.md CHANGED
@@ -494,6 +494,149 @@ null` и этого правила засчитанных попыток: ист
494
494
  без записанного повтора (`recorded.gaps`, ограничение `recording-gap`); иной
495
495
  пробел не виден, и отчёт всегда называет это ограничением (`rollback-gap`).
496
496
 
497
+ ### alpha.35: нехватка окна контекста
498
+
499
+ Номера форматов прежние (`stateVersion: 1`, `policyVersion: 1`), новое —
500
+ аддитивно:
501
+
502
+ - **Состояние и журнал.** Класс отказа `context-exhausted` в `failureKind`
503
+ (попытка, поручение, `attempt.failed`, `attempt.diagnosed`, причина
504
+ `explain`, пакет передачи и отчёт — корзина `incomplete`) и необязательное
505
+ поле `AttemptState.contextLimit` (`prompt-too-long` | `blocking-limit`).
506
+ - **Коды.** `CONTEXT_EXHAUSTED` (класс `refused`, exit code 3) — код
507
+ остановки этого класса (`stopReason` результата, `explain`, пакет передачи;
508
+ в `cliCommands.run.refusals`).
509
+ - **Политика.** `repairPolicy['context-exhausted']`: один повтор у
510
+ `blocking-limit`, ни одного у `prompt-too-long` (`repairRepeats`); попытка
511
+ засчитывается. `prompt-too-long` — только `prompt_too_long` на первом ходе
512
+ (`num_turns` ≤ 1); тот же признак после ходов работы — `blocking-limit`.
513
+ - **API.** `repairRepeats` и `lastContextLimit` экспортированы рядом с
514
+ `repairPolicy`.
515
+ - **Порт runtime.** Необязательное поле
516
+ `RuntimeResponse.diagnostics.contextExhausted` (предел окна); адаптер без
517
+ него — прежняя классификация. В `runtime.json` вызова claude —
518
+ `terminalReason` и `compactions` (диагностика, не договор).
519
+
520
+ Прежде такой отказ claude получал класс `unknown` (у reviewer — `review`).
521
+ Читатель, проверявший строгой схемой прежней версии `ValueReport`, пакет
522
+ передачи (`handoff-pack`), диагноз остановки (`stop-diagnosis`) или
523
+ `RunResult`, отклонит новые значения `context-exhausted` и
524
+ `CONTEXT_EXHAUSTED`: обновить схему вместе с пакетом.
525
+
526
+ **Откат.** Документ состояния разбирается строго: alpha.34 и ниже отказывают
527
+ на документе с отказом `context-exhausted` или полем `contextLimit`. Путь —
528
+ строка «Новая версия уже изменила формат» таблицы [«Откат»](#откат):
529
+ остановить writers и восстановить копию каталога состояния, снятую до
530
+ обновления, вместе с прежней версией пакета.
531
+
532
+ ### 0.1.0-alpha.36: зависимости исполнителя и факты проекта
533
+
534
+ Номера форматов прежние (`stateVersion: 1`, `policyVersion: 1`); без
535
+ `repositories[].writerDependencies` политика и её digest не меняются. Новое
536
+ поведение включено по умолчанию и действует при любом `isolation.mode` (при
537
+ `none` — без песочницы, как gates): перед исполнителем, после наложения
538
+ черновика прежней попытки, controller исполняет в его дереве обязательные gates
539
+ установки попытки под изоляцией gate, без evidence. Отказ — заметка
540
+ исполнителю (вывод установки — строкой JSON с пометкой «untrusted»);
541
+ защищённый путь над базой — `environment`/`sandbox-policy`, над черновиком —
542
+ `scope-violation`. Следы установки не попадают в работу исполнителя: новые
543
+ `node_modules` где угодно в дереве скрыты собственным `.gitignore`, прочие
544
+ новые неотслеживаемые пути убраны (квитанция `removed`), правка отслеживаемых
545
+ файлов откатывается. Попытка получает стадию `writer-dependencies` в
546
+ `timings`. Поле необязательно, строгая схема прежних версий его не принимает:
547
+ при откате уберите его из политики. Подробнее —
548
+ [зависимости исполнителя](toolchains.md#зависимости-исполнителя).
549
+
550
+ ### 0.1.0-alpha.37: вопросы исполнителя и диагностика многих работ
551
+
552
+ Номера форматов прежние (`stateVersion: 1`, `policyVersion: 1`, `apiVersion`
553
+ прежний); новое — аддитивно, подробности — [вопрос исполнителя](contracts.md#вопрос-исполнителя):
554
+
555
+ - **Политика.** Необязательное `inputPolicy {threshold 1–11, criticalPaths}`;
556
+ без поля политика и её digest прежние, порог — 7. В `executionDigest` поле
557
+ не входит: его смена не требует нового согласования графа и действует со
558
+ следующей попытки.
559
+ - **Ответ writer.** Необязательные `inputRequest` и `assumptions`;
560
+ wire-схема CLI runtime объявляет оба поля. `completed: true` с вопросом —
561
+ ответ вне схемы. Ответ прежнего формата читается как прежде.
562
+ - **Состояние.** Локальное пространство `input-requests` (`InputRequest`,
563
+ `schemas/input-request.schema.json`); необязательные поля попытки
564
+ `inputPolicy`, `assumptions`, `input` и `pinned.contextDigest`. Класс
565
+ отказа `needs-input`. Состояние без вопросов читается без изменений: запросов
566
+ нет, выдача и повтор прежние.
567
+ - **Коды и журнал.** `INPUT_REQUIRED` (класс `refused`, exit code 3; в
568
+ отказах `run`, `retry`, `approve`); события `input.requested`,
569
+ `input.answered`, `input.applied`, `input.closed`, `input.delivered`,
570
+ `attempt.assumptions`, `input.stale` (ID, digests и числа); типы
571
+ транзакций `input.*`. Необязательные поля запроса `stale` и `normalized`.
572
+ Причина остановки `needs-input`, действия `answer-input` и `apply-input`.
573
+ - **Проекции.** `status`: `works[].input`, `works[].followUps`; пакет передачи:
574
+ блок `inputs` и `truncated.inputs`; отчёт: блок `inputs` (только числа) и
575
+ корзина отказов `input`.
576
+ - **Порты.** Необязательный `ExecutionHost.input` (`InputHost`) для хоста,
577
+ ведущего согласование сам; `RunnerOptions.context(work, attempt)` получает
578
+ выданную попытку (снимок загружается по `attempt.pinned.contextDigest`);
579
+ `measuredInvoke` — необязательный `onStart(callId)` (доставку ответа
580
+ runner подтверждает не им, а ответом runtime, отличным от `unavailable`). Набор
581
+ `executionStoreContract` проверяет пространство `input-requests`;
582
+ `sampleInputRequest`/`answeredInputRequest` экспортированы из
583
+ `devcontour-harness/testing`.
584
+ - **CLI.** Команды `input-list`, `input-show`, `input-answer`,
585
+ `input-context`, `input-target`, `input-apply`, `input-cancel`,
586
+ `input-supersede`.
587
+ - **Хост с портом согласования.** `InputHost.review` и `activate`
588
+ получают запрос (`{id, answerDigest, mode}`); перенос ответа заменённого
589
+ запроса — `Engine.proposeCarry` и `Engine.carryInput` (`expectedVersion`,
590
+ `targetDigest`; `Harness.proposeCarry`/`carryInput`). Экспортированный
591
+ `unappliedInputs` требует `mayCarry`. `originBasis.contentDigest` —
592
+ необязательное поле запроса, `target.contentDigest` — цели; состояние
593
+ вопроса `carry-stale` (status, handoff); `cancelInput` снимает устаревший
594
+ перенесённый ответ. Не найденный закреплённый снимок держит только свою
595
+ работу (`needs-lead`, не засчитана), очередь не останавливается. Исходная остановка и
596
+ устаревание применённого ответа сравнивают постановку самой работы, а не
597
+ digest графа. Попытка с `pinned.contextDigest` отказывает, если загрузчик
598
+ контекста хоста вернул другой снимок. `implementationOutputSchema`
599
+ (wire-схема ответа writer) экспортирован корнем пакета.
600
+ - **Маскирование.** Ответ writer маскируется полным окружением вызова до
601
+ разбора: `hooks.implemented` получает уже замаскированный `output`
602
+ (`summary`, `discoveries`). Наследуемые переменные (`environment.inherit`)
603
+ маскируются, если значение не короче 8 знаков или имя похоже на секрет
604
+ (TOKEN, SECRET, PASSWORD, API_KEY, CREDENTIAL, AUTH, PRIVATE; значение от 4
605
+ знаков); объявленные `secrets` — всегда. Не маскируются только наследуемые
606
+ значения короче 8 знаков без секретного имени (`FORCE_COLOR=1`, `CI=true`):
607
+ прежде они вырезались из каждой строки вывода проверок и ответов. Короткий
608
+ секрет без секретного имени объявите в `secrets`.
609
+ - **Поведение `unfinished`.** Защищённые пути, HEAD и область записи
610
+ проверяются до решения о вопросе и незавершённости для любого ответа
611
+ writer. Прежде `completed: false` с правкой вне области получал
612
+ `unfinished` и продолжался с черновика в области; теперь это
613
+ `scope-violation` (повтор по его правилу), как у готовой реализации.
614
+
615
+ - **Диагностика многих работ.** `stopInputsOf` принимает `workIds`;
616
+ `Engine.budgetBlocksOf(workIds | undefined, view)` даёт блокировки бюджета
617
+ набора работ за одно чтение (значение равно `budgetBlockOf`). Вызов для
618
+ всей доски линеен по числу работ. Поведение прежнее.
619
+ - **Перенос и объяснение.** Снятие устаревшего перенесённого ответа хранит
620
+ запись замены в `closed.previous`; отказ до старта попытки объясняется фазой
621
+ `preflight` (`StopInput.work.preflight`).
622
+ - **Отчёт.** `report.inputs.carryStale` — новое число; `report.inputs.closed`
623
+ больше не считает вопросы с устаревшим перенесённым ответом.
624
+
625
+ Читатель со строгой схемой прежней версии `ValueReport`, `HandoffPack`,
626
+ `StopDiagnosis`, `RunEvent`, `RunResult` или ответа `status` отклонит новые
627
+ значения и поля: обновить схему вместе с пакетом. Хост с собственным
628
+ хранилищем (DevContour) хранит `input-requests` у владельца-компонента, а
629
+ адаптер прогоняет расширенный `executionStoreContract`.
630
+
631
+ **Откат.** Документ состояния разбирается строго: прежние версии отказывают
632
+ до записи на попытке с полями `inputPolicy`, `assumptions`, `input` или
633
+ `pinned.contextDigest` (их пишет каждая новая выдача) и на отказе
634
+ `needs-input`; записи `input-requests` прежняя версия не читает. Путь —
635
+ строка «Новая версия уже изменила формат» таблицы [«Откат»](#откат):
636
+ остановить writers и восстановить копию каталога состояния, снятую до
637
+ обновления, вместе с прежней версией пакета; поле `inputPolicy` убрать из
638
+ политики.
639
+
497
640
  ## Перед обновлением
498
641
 
499
642
  1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
@@ -1,5 +1,14 @@
1
1
  import type { z } from 'zod';
2
- import type { ProbeServer, RuntimeAdapter, toolProfileSchema } from '../contracts/index.ts';
2
+ import type { ContextLimit, ProbeServer, RuntimeAdapter, toolProfileSchema } from '../contracts/index.ts';
3
+ /**
4
+ * Предел окна контекста по итоговому событию claude. `prompt_too_long` на
5
+ * первом ходе (`num_turns` ≤ 1, записанный случай: подсказка сама больше
6
+ * окна) — `prompt-too-long`, повтор только удлинит подсказку. Тот же признак
7
+ * после ходов работы (окно заполнил вывод инструментов) и без `num_turns` —
8
+ * `blocking-limit`, как остановка CLI у предела окна: повтор может читать
9
+ * меньше.
10
+ */
11
+ export declare function claudeContextLimit(terminalReason: string | undefined, numTurns: number | undefined): ContextLimit | undefined;
3
12
  type ToolProfile = z.infer<typeof toolProfileSchema>;
4
13
  /**
5
14
  * Предел файла ответа codex: вдвое выше хвоста stdout, в котором приходит ответ
@@ -10,6 +10,21 @@ import { inspectReview } from "./inspect.js";
10
10
  import { probeCallMs, probeServer, probeTool } from "./review-probe.js";
11
11
  import { claudeResult, runtimeEvents } from "./runtime-events.js";
12
12
  import { runtimeVersion, unknownUsage, usageStream } from "./usage.js";
13
+ /**
14
+ * Предел окна контекста по итоговому событию claude. `prompt_too_long` на
15
+ * первом ходе (`num_turns` ≤ 1, записанный случай: подсказка сама больше
16
+ * окна) — `prompt-too-long`, повтор только удлинит подсказку. Тот же признак
17
+ * после ходов работы (окно заполнил вывод инструментов) и без `num_turns` —
18
+ * `blocking-limit`, как остановка CLI у предела окна: повтор может читать
19
+ * меньше.
20
+ */
21
+ export function claudeContextLimit(terminalReason, numTurns) {
22
+ if (terminalReason === 'blocking_limit')
23
+ return 'blocking-limit';
24
+ if (terminalReason !== 'prompt_too_long')
25
+ return undefined;
26
+ return numTurns !== undefined && numTurns <= 1 ? 'prompt-too-long' : 'blocking-limit';
27
+ }
13
28
  /**
14
29
  * Предел файла ответа codex: вдвое выше хвоста stdout, в котором приходит ответ
15
30
  * claude (2 000 000 символов). Ответ модели на порядки меньше, а разбор
@@ -328,9 +343,20 @@ export function cliAdapter(runtime, options = {}) {
328
343
  }
329
344
  const usage = telemetry.usage(result.code === 0 && !result.timedOut && !signal.aborted);
330
345
  const model = telemetry.model();
346
+ const terminalReason = telemetry.terminalReason();
347
+ const compactions = telemetry.compactions();
331
348
  // Сообщённые runtime счётчики и стоимость — и в диагностике вызова:
332
- // runtime.log ограничен и итоговой строки может не содержать.
333
- await writeFile(join(dir, 'runtime.json'), JSON.stringify({ ...result.diagnostics, usage }, null, 2));
349
+ // runtime.log ограничен и итоговой строки может не содержать. Там же
350
+ // исход хода claude и число сжатий контекста (успешное сжатие — не отказ).
351
+ await writeFile(join(dir, 'runtime.json'), JSON.stringify({
352
+ ...result.diagnostics,
353
+ usage,
354
+ ...(terminalReason ? { terminalReason } : {}),
355
+ ...(compactions ? { compactions } : {}),
356
+ }, null, 2));
357
+ // Нехватка окна контекста — по `terminal_reason` итогового события
358
+ // claude, а не по тексту причины (в нём числа токенов).
359
+ const contextExhausted = runtime === 'claude' ? claudeContextLimit(terminalReason, telemetry.numTurns()) : undefined;
334
360
  const bookkeeping = ['system', 'result', 'error', 'session.created', 'thread.started'];
335
361
  const started = result.timedOut ||
336
362
  runtimeEvents(result.stdout).events.some((e) => !bookkeeping.includes(String(e.type)));
@@ -359,6 +385,7 @@ export function cliAdapter(runtime, options = {}) {
359
385
  exitCode: result.code,
360
386
  ...(why ? { reason: why } : {}),
361
387
  log: logPath,
388
+ ...(contextExhausted ? { contextExhausted } : {}),
362
389
  });
363
390
  const expired = signal.aborted && signal.reason?.name === 'TimeoutError';
364
391
  if (result.timedOut || expired)
@@ -372,7 +399,8 @@ export function cliAdapter(runtime, options = {}) {
372
399
  if (result.code !== 0)
373
400
  return {
374
401
  ...base,
375
- status: started ? 'failed' : 'unavailable',
402
+ // Нехватка окна — ответ runtime о запросе, а не недоступный runtime.
403
+ status: started || contextExhausted ? 'failed' : 'unavailable',
376
404
  diagnostics: diagnostics(`код ${result.code}${reason() ? ': ' + reason() : ''}`),
377
405
  };
378
406
  let output;
@@ -383,14 +411,17 @@ export function cliAdapter(runtime, options = {}) {
383
411
  output = JSON.parse(cleaned);
384
412
  }
385
413
  else {
386
- const final = claudeResult.parse(runtimeEvents(result.stdout).events.findLast((e) => e.type === 'result'));
387
- if (final.is_error)
414
+ const last = runtimeEvents(result.stdout).events.findLast((e) => e.type === 'result');
415
+ // `is_error` проверяется до разбора: `claudeResult` требует поле
416
+ // `structured_output`, которого у такого `result` нет, и отказ
417
+ // runtime при коде 0 читался как непрочитанный ответ.
418
+ if (last?.is_error === true)
388
419
  return {
389
420
  ...base,
390
421
  status: 'failed',
391
- diagnostics: diagnostics(redact(final.result ?? 'ошибка runtime').slice(0, 300)),
422
+ diagnostics: diagnostics(redact(typeof last.result === 'string' ? last.result : 'ошибка runtime').slice(0, 300)),
392
423
  };
393
- output = final.structured_output;
424
+ output = claudeResult.parse(last).structured_output;
394
425
  }
395
426
  }
396
427
  catch (error) {
@@ -42,6 +42,88 @@ export declare const implementationOutputSchema: {
42
42
  required: string[];
43
43
  };
44
44
  };
45
+ inputRequest: {
46
+ type: string[];
47
+ additionalProperties: boolean;
48
+ properties: {
49
+ question: {
50
+ type: string;
51
+ };
52
+ options: {
53
+ type: string;
54
+ maxItems: 6;
55
+ items: {
56
+ type: string;
57
+ additionalProperties: boolean;
58
+ properties: {
59
+ id: {
60
+ type: string;
61
+ };
62
+ label: {
63
+ type: string;
64
+ };
65
+ consequence: {
66
+ type: string[];
67
+ };
68
+ };
69
+ required: string[];
70
+ };
71
+ };
72
+ recommended: {
73
+ type: string[];
74
+ };
75
+ severity: {
76
+ type: string;
77
+ minimum: number;
78
+ maximum: number;
79
+ };
80
+ rationale: {
81
+ type: string;
82
+ };
83
+ affects: {
84
+ type: string;
85
+ maxItems: 5;
86
+ items: {
87
+ type: string;
88
+ enum: ("acceptance" | "contract" | "product" | "api" | "migration")[];
89
+ };
90
+ };
91
+ };
92
+ required: string[];
93
+ };
94
+ assumptions: {
95
+ type: string;
96
+ maxItems: 20;
97
+ items: {
98
+ type: string;
99
+ additionalProperties: boolean;
100
+ properties: {
101
+ question: {
102
+ type: string;
103
+ };
104
+ chosen: {
105
+ type: string;
106
+ };
107
+ rationale: {
108
+ type: string;
109
+ };
110
+ severity: {
111
+ type: string;
112
+ minimum: number;
113
+ maximum: number;
114
+ };
115
+ affects: {
116
+ type: string;
117
+ maxItems: 5;
118
+ items: {
119
+ type: string;
120
+ enum: ("acceptance" | "contract" | "product" | "api" | "migration")[];
121
+ };
122
+ };
123
+ };
124
+ required: string[];
125
+ };
126
+ };
45
127
  };
46
128
  required: string[];
47
129
  };
@@ -207,7 +289,7 @@ export declare const reviewOutputSchema: {
207
289
  };
208
290
  status: {
209
291
  type: string;
210
- enum: ("open" | "closed" | "withdrawn")[];
292
+ enum: ("closed" | "open" | "withdrawn")[];
211
293
  };
212
294
  basis: {
213
295
  type: string;
@@ -410,7 +492,7 @@ export declare const alreadySatisfiedReviewOutputSchema: {
410
492
  };
411
493
  status: {
412
494
  type: string;
413
- enum: ("open" | "closed" | "withdrawn")[];
495
+ enum: ("closed" | "open" | "withdrawn")[];
414
496
  };
415
497
  basis: {
416
498
  type: string;
@@ -1,4 +1,5 @@
1
1
  import { FINDING_BASIS_PATTERN, FINDING_ID_PATTERN, REVIEW_ITEMS_LIMIT, findingStatuses, } from "../contracts/review.js";
2
+ import { INPUT_LIMITS, INPUT_SEVERITY_MAX, criticalAreas } from "../contracts/input.js";
2
3
  /**
3
4
  * JSON Schema структурированного ответа для CLI runtime. Codex требует
4
5
  * закрытые объекты, где каждое свойство обязательно (необязательность —
@@ -19,6 +20,51 @@ const discovery = {
19
20
  },
20
21
  required: ['kind', 'title', 'path', 'line', 'observation', 'consequence', 'reproduction'],
21
22
  };
23
+ const areas = {
24
+ type: 'array',
25
+ maxItems: criticalAreas.length,
26
+ items: { type: 'string', enum: [...criticalAreas] },
27
+ };
28
+ const severity = { type: 'integer', minimum: 1, maximum: INPUT_SEVERITY_MAX };
29
+ /** Вопрос исполнителя (`inputQuestionSchema`); `null` — вопроса нет. */
30
+ const inputRequest = {
31
+ type: ['object', 'null'],
32
+ additionalProperties: false,
33
+ properties: {
34
+ question: { type: 'string' },
35
+ options: {
36
+ type: 'array',
37
+ maxItems: INPUT_LIMITS.options,
38
+ items: {
39
+ type: 'object',
40
+ additionalProperties: false,
41
+ properties: {
42
+ id: { type: 'string' },
43
+ label: { type: 'string' },
44
+ consequence: { type: ['string', 'null'] },
45
+ },
46
+ required: ['id', 'label', 'consequence'],
47
+ },
48
+ },
49
+ recommended: { type: ['string', 'null'] },
50
+ severity,
51
+ rationale: { type: 'string' },
52
+ affects: areas,
53
+ },
54
+ required: ['question', 'options', 'recommended', 'severity', 'rationale', 'affects'],
55
+ };
56
+ const assumption = {
57
+ type: 'object',
58
+ additionalProperties: false,
59
+ properties: {
60
+ question: { type: 'string' },
61
+ chosen: { type: 'string' },
62
+ rationale: { type: 'string' },
63
+ severity,
64
+ affects: areas,
65
+ },
66
+ required: ['question', 'chosen', 'rationale', 'severity', 'affects'],
67
+ };
22
68
  export const implementationOutputSchema = {
23
69
  type: 'object',
24
70
  additionalProperties: false,
@@ -26,8 +72,10 @@ export const implementationOutputSchema = {
26
72
  completed: { type: 'boolean' },
27
73
  summary: { type: 'string' },
28
74
  discoveries: { type: 'array', maxItems: 20, items: discovery },
75
+ inputRequest,
76
+ assumptions: { type: 'array', maxItems: INPUT_LIMITS.assumptions, items: assumption },
29
77
  },
30
- required: ['completed', 'summary', 'discoveries'],
78
+ required: ['completed', 'summary', 'discoveries', 'inputRequest', 'assumptions'],
31
79
  };
32
80
  export const reviewOutputSchema = {
33
81
  type: 'object',
@@ -16,6 +16,9 @@ export declare const LINE_LIMIT = 8000000;
16
16
  * учитывалась неполной. Здесь каждая строка разбирается сразу; хранятся
17
17
  * только поля телеметрии — последнее событие `result`, события
18
18
  * `turn.completed` и первая сообщённая модель, — а не текст вывода.
19
+ * У claude также — `terminal_reason` и `num_turns` последнего `result` (по
20
+ * ним адаптер узнаёт нехватку окна контекста) и число автоматических и ручных сжатий
21
+ * контекста (`system`/`compact_boundary`): успешное сжатие не отказ.
19
22
  */
20
23
  export declare function usageStream(runtime: 'codex' | 'claude'): {
21
24
  /**
@@ -27,4 +30,10 @@ export declare function usageStream(runtime: 'codex' | 'claude'): {
27
30
  /** Телеметрия всего потока; `completed` — вызов завершился штатно. */
28
31
  usage(completed: boolean): Usage;
29
32
  model: () => string | null;
33
+ /** `terminal_reason` последнего `result` claude; нет — runtime не сообщил. */
34
+ terminalReason: () => string | undefined;
35
+ /** `num_turns` последнего `result` claude; нет — runtime не сообщил. */
36
+ numTurns: () => number | undefined;
37
+ /** Сколько раз runtime сжал контекст за вызов (`compact_boundary`). */
38
+ compactions: () => number;
30
39
  };