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.
- package/README.md +43 -16
- package/docs/architecture.md +12 -0
- package/docs/compatibility.md +21 -18
- package/docs/contracts.md +270 -12
- package/docs/release-notes/0.1.0-alpha.31.md +44 -0
- package/docs/release-notes/0.1.0-alpha.32.md +33 -0
- package/docs/release-notes/0.1.0-alpha.33.md +29 -0
- package/docs/release-notes/0.1.0-alpha.34.md +32 -0
- package/docs/upgrade.md +181 -0
- package/lib/agents/cli-adapter.js +1 -0
- package/lib/cli.js +25 -3
- package/lib/contracts/cli.d.ts +1381 -18
- package/lib/contracts/cli.js +43 -1
- package/lib/contracts/diagnosis.d.ts +2 -1
- package/lib/contracts/diagnosis.js +1 -0
- package/lib/contracts/events.d.ts +760 -5
- package/lib/contracts/events.js +109 -3
- package/lib/contracts/execution.d.ts +112 -1
- package/lib/contracts/execution.js +38 -0
- package/lib/contracts/failure.d.ts +6 -1
- package/lib/contracts/failure.js +5 -1
- package/lib/contracts/handoff.d.ts +702 -0
- package/lib/contracts/handoff.js +305 -0
- package/lib/contracts/index.d.ts +1 -0
- package/lib/contracts/index.js +1 -0
- package/lib/contracts/policy.d.ts +27 -1
- package/lib/contracts/policy.js +38 -2
- package/lib/contracts/published.d.ts +1016 -3
- package/lib/contracts/published.js +2 -0
- package/lib/contracts/repair-policy.js +5 -0
- package/lib/contracts/report.d.ts +118 -2
- package/lib/contracts/report.js +61 -3
- package/lib/control/base-move.d.ts +7 -2
- package/lib/control/base-move.js +14 -1
- package/lib/control/harness.d.ts +81 -19
- package/lib/control/harness.js +8 -93
- package/lib/control/recovery.d.ts +1 -1
- package/lib/control/status.d.ts +235 -0
- package/lib/control/status.js +101 -0
- package/lib/engine/budget.d.ts +78 -0
- package/lib/engine/budget.js +13 -2
- package/lib/engine/classify.d.ts +14 -1
- package/lib/engine/classify.js +34 -0
- package/lib/engine/engine.d.ts +31 -11
- package/lib/engine/engine.js +99 -5
- package/lib/engine/joint-runner.d.ts +6 -0
- package/lib/engine/joint-runner.js +20 -4
- package/lib/engine/property-recovery.js +1 -0
- package/lib/engine/reuse.js +1 -0
- package/lib/engine/runner.d.ts +8 -0
- package/lib/engine/runner.js +120 -16
- package/lib/engine/stall-sweep.d.ts +137 -0
- package/lib/engine/stall-sweep.js +393 -0
- package/lib/environment/activity.d.ts +34 -0
- package/lib/environment/activity.js +55 -0
- package/lib/environment/isolation.d.ts +67 -3
- package/lib/environment/isolation.js +148 -5
- package/lib/environment/lifecycle.js +2 -1
- package/lib/environment/process.d.ts +7 -1
- package/lib/environment/process.js +14 -0
- package/lib/environment/redaction.d.ts +2 -0
- package/lib/environment/redaction.js +19 -0
- package/lib/explain/state.d.ts +26 -5
- package/lib/explain/state.js +41 -0
- package/lib/handoff/index.d.ts +2 -0
- package/lib/handoff/index.js +3 -0
- package/lib/handoff/markdown.d.ts +6 -0
- package/lib/handoff/markdown.js +155 -0
- package/lib/handoff/pack.d.ts +79 -0
- package/lib/handoff/pack.js +531 -0
- package/lib/index.d.ts +19 -3
- package/lib/index.js +18 -1
- package/lib/integrations/connector/redact.d.ts +2 -13
- package/lib/integrations/connector/redact.js +2 -21
- package/lib/integrations/connector/testing.js +1 -1
- package/lib/projections/attempt.d.ts +28 -0
- package/lib/projections/attempt.js +14 -0
- package/lib/projections/next.d.ts +3 -1
- package/lib/projections/next.js +4 -1
- package/lib/projections/stop.d.ts +22 -1
- package/lib/projections/stop.js +73 -15
- package/lib/report/compute.js +229 -21
- package/lib/report/document.js +31 -7
- package/lib/storage/document.d.ts +28 -6
- package/lib/storage/sqlite.d.ts +2 -0
- package/lib/storage/sqlite.js +9 -1
- package/lib/verification/gates-at.d.ts +11 -1
- package/lib/verification/gates-at.js +28 -2
- package/lib/verification/gates.d.ts +3 -1
- package/lib/verification/gates.js +25 -4
- package/package.json +1 -1
- package/schemas/execution-document.schema.json +68 -0
- package/schemas/execution-policy.schema.json +32 -0
- package/schemas/handoff-pack.schema.json +1430 -0
- package/schemas/run-event.schema.json +679 -0
- package/schemas/stop-diagnosis.schema.json +1 -0
- 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.
|
|
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.
|
|
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`
|
|
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`
|
|
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
|
|
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` для
|
package/docs/architecture.md
CHANGED
|
@@ -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 и вокруг работы исполнителя
|
package/docs/compatibility.md
CHANGED
|
@@ -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`)
|
|
46
|
-
|
|
47
|
-
`
|
|
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
|
-
|
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
|
|
|
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
|
|
756
|
-
не называют (удерживают и
|
|
757
|
-
показаны отдельно (`holds
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
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`, `--
|
|
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#что-гарантируется), «Сеть и реестр при установке зависимостей»). Отдельного поля
|