devcontour-harness 0.1.0-alpha.29 → 0.1.0-alpha.31
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 +50 -14
- package/docs/architecture.md +64 -0
- package/docs/compatibility.md +15 -14
- package/docs/contracts.md +380 -26
- package/docs/release-notes/0.1.0-alpha.30.md +40 -0
- package/docs/release-notes/0.1.0-alpha.31.md +44 -0
- package/docs/review-probes.md +17 -17
- package/docs/upgrade.md +137 -0
- package/lib/agents/cli-adapter.js +1 -0
- package/lib/agents/review-probe.d.ts +1 -0
- package/lib/agents/review-probe.js +20 -0
- package/lib/cli.js +79 -1
- package/lib/contracts/cli.d.ts +2216 -15
- package/lib/contracts/cli.js +171 -4
- package/lib/contracts/diagnosis.d.ts +2 -1
- package/lib/contracts/diagnosis.js +1 -0
- package/lib/contracts/events.d.ts +1052 -4
- package/lib/contracts/events.js +94 -1
- package/lib/contracts/execution.d.ts +112 -1
- package/lib/contracts/execution.js +38 -0
- package/lib/contracts/handoff.d.ts +694 -0
- package/lib/contracts/handoff.js +291 -0
- package/lib/contracts/index.d.ts +2 -0
- package/lib/contracts/index.js +2 -0
- package/lib/contracts/policy.d.ts +27 -1
- package/lib/contracts/policy.js +38 -2
- package/lib/contracts/ports.d.ts +5 -1
- package/lib/contracts/published.d.ts +1398 -2
- package/lib/contracts/published.js +4 -0
- package/lib/contracts/repair-policy.js +5 -0
- package/lib/contracts/report.d.ts +1151 -0
- package/lib/contracts/report.js +401 -0
- package/lib/control/harness.d.ts +486 -7
- package/lib/control/harness.js +86 -1
- package/lib/control/recovery.d.ts +1 -1
- package/lib/control/report-file.d.ts +19 -0
- package/lib/control/report-file.js +85 -0
- package/lib/control/report.d.ts +9 -0
- package/lib/control/report.js +27 -0
- package/lib/engine/engine.d.ts +20 -8
- package/lib/engine/engine.js +73 -7
- 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 +121 -13
- 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/dependency-network.d.ts +42 -0
- package/lib/environment/dependency-network.js +413 -0
- package/lib/environment/lifecycle.d.ts +3 -1
- package/lib/environment/lifecycle.js +23 -4
- package/lib/environment/process.d.ts +12 -1
- package/lib/environment/process.js +52 -0
- package/lib/environment/redaction.d.ts +2 -0
- package/lib/environment/redaction.js +19 -0
- package/lib/explain/state.d.ts +38 -0
- package/lib/explain/state.js +31 -11
- 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 +153 -0
- package/lib/handoff/pack.d.ts +49 -0
- package/lib/handoff/pack.js +492 -0
- package/lib/index.d.ts +4 -1
- package/lib/index.js +3 -0
- package/lib/integrations/connector/redact.d.ts +2 -13
- package/lib/integrations/connector/redact.js +2 -21
- package/lib/projections/attempt.d.ts +129 -0
- package/lib/projections/attempt.js +78 -0
- package/lib/projections/index.d.ts +2 -1
- package/lib/projections/index.js +2 -1
- package/lib/projections/stop.d.ts +30 -1
- package/lib/projections/stop.js +59 -24
- package/lib/report/compute.d.ts +72 -0
- package/lib/report/compute.js +1220 -0
- package/lib/report/document.d.ts +27 -0
- package/lib/report/document.js +206 -0
- package/lib/report/format.d.ts +23 -0
- package/lib/report/format.js +53 -0
- package/lib/report/html.d.ts +7 -0
- package/lib/report/html.js +109 -0
- package/lib/report/index.d.ts +4 -0
- package/lib/report/index.js +7 -0
- package/lib/report/markdown.d.ts +7 -0
- package/lib/report/markdown.js +112 -0
- package/lib/storage/document.d.ts +28 -6
- package/lib/storage/sqlite.d.ts +21 -0
- package/lib/storage/sqlite.js +70 -7
- package/lib/verification/gates-at.d.ts +11 -1
- package/lib/verification/gates-at.js +28 -2
- package/lib/verification/gates.d.ts +9 -1
- package/lib/verification/gates.js +20 -0
- package/package.json +5 -1
- package/schemas/execution-document.schema.json +68 -0
- package/schemas/execution-policy.schema.json +32 -0
- package/schemas/handoff-pack.schema.json +1424 -0
- package/schemas/run-event.schema.json +455 -0
- package/schemas/stop-diagnosis.schema.json +1 -0
- package/schemas/value-report.schema.json +2542 -0
package/docs/contracts.md
CHANGED
|
@@ -32,7 +32,9 @@ refs, варианты исходов. Связи **между** значени
|
|
|
32
32
|
|
|
33
33
|
Опубликованы: `work-order`, `work-graph`, `execution-policy`,
|
|
34
34
|
`context-snapshot`, `contract-document`, `run-result`, `result-envelope`,
|
|
35
|
-
`run-event`, `review-record`, `joint-verification`, `execution-document
|
|
35
|
+
`run-event`, `review-record`, `joint-verification`, `execution-document`,
|
|
36
|
+
`value-report` (отчёт `harness report`, см. «ValueReport»), `handoff-pack`
|
|
37
|
+
(пакет `harness handoff`, см. «HandoffPack»).
|
|
36
38
|
|
|
37
39
|
## Версии
|
|
38
40
|
|
|
@@ -107,6 +109,7 @@ manifest снимка и в необязательном поле `baseline` о
|
|
|
107
109
|
| `toolProfiles{}`, `environment`, `lifecycle`, `resources[]` | Инструменты (у профиля — встроенные инструменты claude, shell и сеть codex, MCP-серверы `mcp{}`: stdio-команда или http-адрес, только перечисленные `tools`, учётные данные — именами переменных `env`/`bearerTokenEnv`, передаются CLI по имени), среда, ресурсы (порты 1024–65535) |
|
|
108
110
|
| `concurrency`, `leaseMs`, `runTimeoutMs`, `reviewProbes` | Пределы исполнения |
|
|
109
111
|
| `maxAttempts`, `repairBudget`, `reuseImplementation` | Повторы и повторное использование кандидата |
|
|
112
|
+
| `stallSweep{intervalMs, quietMs, stalledMs, action}` | Необязательное: обход зависших попыток controller ([ниже](#зависшие-попытки)); нет поля — 30 000 / 180 000 / 600 000 мс и `report`, умолчание не подставляется и digest политики не меняет |
|
|
110
113
|
| `reviewProtocolRetries` | Необязательное: дополнительные вызовы reviewer кода при ошибке протокола ответа (0–2; нет поля — 1, умолчание не подставляется и digest политики не меняет), [review-protocol.md](review-protocol.md) |
|
|
111
114
|
| `budgets{work, group, total, onUnknown}`, `prices[]` | Пределы USD и/или времени; тарифы |
|
|
112
115
|
|
|
@@ -612,6 +615,51 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
|
|
|
612
615
|
закреплён, `impact` может нести только ссылку на базовую проверку
|
|
613
616
|
(`baseline`), выбранную хостом для режима `affected`.
|
|
614
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
|
+
|
|
615
663
|
### RunEvent
|
|
616
664
|
|
|
617
665
|
`{apiVersion, seq, at, type, graphId?, workId?, runId?, attempt?, payload}`.
|
|
@@ -619,6 +667,46 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
|
|
|
619
667
|
схема: лишних полей нет, поэтому токен владения, секрет или объект попытки в
|
|
620
668
|
событие не попадает.
|
|
621
669
|
|
|
670
|
+
`attempt.stage` — граница стадии попытки: `{timingId, stage, phase:
|
|
671
|
+
'started'|'finished', at, durationMs?, outcome?: 'passed'|'failed'}`, конверт
|
|
672
|
+
несёт `graphId`, `workId`, `runId`, `attempt`. Стадии — те же, что замеры
|
|
673
|
+
`AttemptState.timings`: `dependency-store`, `implementation` /
|
|
674
|
+
`implementation-reuse`, `candidate-environment:<шаг>`, `integration-wait`,
|
|
675
|
+
`<фаза>-test:<gate>`, `<фаза>-consumer:<репозиторий>:<gate>`,
|
|
676
|
+
`<фаза>-recheck:<gate>`, `<фаза>-review`, `integration-environment:<шаг>`,
|
|
677
|
+
`integration-consumer-environment:<репозиторий>:<шаг>`. На стадию — одно
|
|
678
|
+
`started` и не больше одного `finished` (у него `durationMs` и `outcome`);
|
|
679
|
+
`at` и `durationMs` — по часам движка и совпадают с замером. Событие пишется
|
|
680
|
+
в той же транзакции `run.timing.started`/`run.timing.finished`, что и замер,
|
|
681
|
+
под fencing: утративший владение не пишет ни замера, ни события. Повторное
|
|
682
|
+
закрытие замера ничего не меняет и событий не создаёт.
|
|
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
|
+
`finished` может не прийти: поздний finish владельца, утратившего срок,
|
|
691
|
+
отклоняется (runner его не повторяет), упавший процесс его не пишет, а `adopt`
|
|
692
|
+
и recovery открытые замеры прежнего владельца не закрывают. Такая стадия
|
|
693
|
+
остаётся открытой и в замере, и в журнале; её конец — событие конца попытки
|
|
694
|
+
(`attempt.expired`, `attempt.failed`, `attempt.cancelled`,
|
|
695
|
+
`attempt.recovered`, `work.accepted`). Потребитель журнала обязан обрабатывать
|
|
696
|
+
незакрытые стадии.
|
|
697
|
+
|
|
698
|
+
Чтение журнала терпимо к типам более новых версий: событие типа, которого нет
|
|
699
|
+
в `eventPayloads`, возвращается как `UnknownRunEvent` —
|
|
700
|
+
`{apiVersion, seq, at, graphId?, workId?, runId?, attempt?, type: 'unknown',
|
|
701
|
+
original}` (исходный тип, не длиннее 200 символов; нагрузка не возвращается).
|
|
702
|
+
`RunEvent` = известные события (`KnownRunEvent`) | `UnknownRunEvent`: нагрузка
|
|
703
|
+
доступна после сужения по `type` (`e.type !== 'unknown'`) или у
|
|
704
|
+
`KnownRunEvent`. Тип `ExecutionStore.events()` прежний (`RunEvent[]`), поэтому
|
|
705
|
+
хранилища хоста, возвращающие или делегирующие события, компилируются без
|
|
706
|
+
изменений. Разбор — `readRunEvent`, схема чтения — `readRunEventSchema`. Запись строгая
|
|
707
|
+
(`runEventSchema`, опубликованная `run-event`): `unknown` записать нельзя;
|
|
708
|
+
известный тип с нарушенной нагрузкой при чтении — отказ.
|
|
709
|
+
|
|
622
710
|
`transactionKinds` — имена транзакций исполнения; совпадают с сохранёнными
|
|
623
711
|
типами событий журнала хоста (`run.claimed`, `task.done`, `run.failed`,
|
|
624
712
|
`scheduler.error`, …). `workflow.updated` пишет только локальные записи
|
|
@@ -640,6 +728,192 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
|
|
|
640
728
|
(`policy.applied`, `policy.reconfigure`). `base.moved` — проверка владения
|
|
641
729
|
операцией и CAS-сдвиг ref базы; записей и событий не создаёт.
|
|
642
730
|
|
|
731
|
+
### ValueReport
|
|
732
|
+
|
|
733
|
+
Отчёт об эффекте (`harness report`, `valueReport` из `devcontour-harness/report`
|
|
734
|
+
и корня пакета; `reportVersion: 1`, `valueReportSchema`,
|
|
735
|
+
`schemas/value-report.schema.json`). Отвечает на вопрос «что дал harness на
|
|
736
|
+
этом проекте» данными самого проекта: только наблюдения (счёт и
|
|
737
|
+
длительности), без «сэкономленных часов» и сравнения «с harness и без»
|
|
738
|
+
(базы до harness в состоянии нет).
|
|
739
|
+
|
|
740
|
+
Вход (`ValueReportInput`) — те же формы, что у `ExecutionView`: `works`,
|
|
741
|
+
`attempts`, `calls` (`locals('usage')`), `reviews` (`locals('reviews')`),
|
|
742
|
+
`events`, `graphs`. `collectReportInput(store)` собирает его из любого
|
|
743
|
+
`ExecutionStore` одним `read` и страницами `events` по 500; `Harness.report()`
|
|
744
|
+
— то же по каталогу состояния. Параметры: `since` (включительно; ISO-время с
|
|
745
|
+
поясом, дата `YYYY-MM-DD` или `Nd`/`Nw` до `asOf`), `until` (не
|
|
746
|
+
включительно), `asOf`, `noTitles`, `label`, `stateDir`, `harnessVersion`.
|
|
747
|
+
`reportMarkdown(report)` и `reportHtml(report)` — чистые рендеры: те же
|
|
748
|
+
разделы и числа; HTML — один файл без скриптов, шрифтов, изображений и
|
|
749
|
+
внешних ссылок (CSP `default-src 'none'; style-src 'unsafe-inline'; img-src
|
|
750
|
+
data:`), светлая и тёмная схема по `prefers-color-scheme`, таблицы
|
|
751
|
+
прокручиваются на ширине телефона, столбики недель (inline SVG) — от 3
|
|
752
|
+
активных недель. Модуль `devcontour-harness/report` без `node:*` и без zod.
|
|
753
|
+
|
|
754
|
+
**Детерминизм.** Тот же вход и параметры — те же байты JSON, Markdown и HTML
|
|
755
|
+
при любом порядке входных массивов, часах и часовом поясе. `asOf` по
|
|
756
|
+
умолчанию — последняя метка времени в данных (событие, начало или конец
|
|
757
|
+
попытки и вызова, раунд ревью), не часы; с `until` раньше неё — `until`.
|
|
758
|
+
Время — UTC ISO, недели — ISO (понедельник, UTC), числа без локали.
|
|
759
|
+
|
|
760
|
+
**Определения.**
|
|
761
|
+
|
|
762
|
+
- Принятое поручение — `WorkState.status = done` с успешной попыткой;
|
|
763
|
+
принявшая попытка — последняя `succeeded`. Поручение `done` без успешной
|
|
764
|
+
попытки не имеет времени приёмки и не входит в принятые ни в каком окне
|
|
765
|
+
(`coverage.doneWithoutAttempt`). В окно входят: принятые — по времени
|
|
766
|
+
приёмки, попытки и вызовы — по началу, раунды ревью и события — по своему
|
|
767
|
+
времени.
|
|
768
|
+
- Попытки поручения считаются по записям попыток, а не по
|
|
769
|
+
`WorkState.attempt` (сброс возвращает счётчик к 0).
|
|
770
|
+
- Корзины отказа попытки (`failureBucketOf`): `defect` (`gate`, `review`,
|
|
771
|
+
`scope-violation`), `incomplete` (`empty-result`, `unfinished`,
|
|
772
|
+
`needs-lead`), `integration` (`stale-base`, `merge`), `environment`
|
|
773
|
+
(`environment`, `provider-auth`, `blocked`, истёкшее владение), `time-limit`
|
|
774
|
+
(`timeout`), `tool` (`review-protocol`), `operator` (`cancelled`), `budget`,
|
|
775
|
+
`unknown`, `unclassified` (попытка без класса — записана до
|
|
776
|
+
классификации; не «дефект»). Прерванная штатной остановкой
|
|
777
|
+
(`interrupted: shutdown`) — не отказ, считается отдельно.
|
|
778
|
+
- Первая попытка — у принятого поручения засчитанная попытка одна
|
|
779
|
+
(засчитанные — без `environment` и прерываний); если, кроме принявшей,
|
|
780
|
+
засчитаны только отказы без класса, — неизвестно (`unknown`, `bound:
|
|
781
|
+
lower`). `firstPassRaw` — попытка вообще одна.
|
|
782
|
+
- Возвращено (`sentBack`) — принятое поручение с попыткой `defect` до
|
|
783
|
+
принявшей. Поручения, у которых до приёмки только отказы без класса
|
|
784
|
+
(`unknown`, `unclassified`), не считаются, а идут в `unknown`: тогда
|
|
785
|
+
`bound: lower` («≥ N», «M more without a class»). Без них, но если часть
|
|
786
|
+
поручений вернули только отказы gate подготовки (установка зависимостей,
|
|
787
|
+
возможна сеть; `sentBackSetupOnly`), — `bound: upper`; оба сомнения
|
|
788
|
+
сразу — `bound: unknown` и диапазон `sentBackRange` («1–3 of 5»); иначе
|
|
789
|
+
`exact`.
|
|
790
|
+
- Ревью после зелёных gates (`afterGreenGates`) — ревью кандидата отклонило,
|
|
791
|
+
хотя каждый обязательный gate прошёл на том же SHA (и той же версии
|
|
792
|
+
проверок); диагностика, не точность reviewer.
|
|
793
|
+
- Срок от согласования до приёмки — от `wait.approvedAt` первой попытки
|
|
794
|
+
(иначе `WorkState.approvedAt`, его переписывает повторное согласование —
|
|
795
|
+
`leadTimeFallback`) до конца принявшей попытки; включает очередь и паузы.
|
|
796
|
+
- Расход: известная цена — правило `knownCost`; на принятое поручение —
|
|
797
|
+
известный расход окна / принятые окна. `callsRecorded` попытки значит
|
|
798
|
+
«учёт её вызовов полон», а не «вызовы есть»: записи вызовов попытки без
|
|
799
|
+
флага входят в её расход, но лишь нижней границей
|
|
800
|
+
(`attemptsPartialCalls`); без флага и без записей расход неизвестен
|
|
801
|
+
(`attemptsWithoutCalls`). `bound: exact` — только если все вызовы окна
|
|
802
|
+
завершены с полными счётчиками и ценой и у всех попыток окна учёт полон;
|
|
803
|
+
иначе `lower` («≥»); без единой известной цены при неизвестных —
|
|
804
|
+
`unknown` (`value: null`), не `$0`. Расход отклонённых попыток
|
|
805
|
+
(`cost.rejected`) и расход отказов окружения (`environment.neutral`) —
|
|
806
|
+
одна и та же атрибуция по всем завершённым попыткам окна.
|
|
807
|
+
- Действия человека — только записи с актёром-человеком: решения recovery
|
|
808
|
+
с источником `operator`. Удержания (`work.held`) и отмены попыток актёра
|
|
809
|
+
не называют (удерживают и операции хоста, например смена контракта): они
|
|
810
|
+
показаны отдельно (`holds`, `cancelledAttempts`) и в действия человека не
|
|
811
|
+
входят. Повторы, сбросы, отмена без попытки и сдвиг базы пока не
|
|
812
|
+
записываются: `withAction` — нижняя граница, «без действий человека»
|
|
813
|
+
(`withoutAction`) пока не измеримо (`value: null`, `bound: unknown`),
|
|
814
|
+
`retries`/`resets`/`baseMoves` — `null`.
|
|
815
|
+
- Отказы окружения (`environment.share`) — среди классифицированных; если
|
|
816
|
+
есть отказы только в gates подготовки (`setupCheckFailures`), доля —
|
|
817
|
+
нижняя граница («at least», «M more may be environment»).
|
|
818
|
+
- Паузы — `control.paused` до следующего `control.resumed` (открытая — до
|
|
819
|
+
`asOf`); время паузы — её пересечение с окном. Согласования — события
|
|
820
|
+
`graph.approved` для графов, у которых такие события есть; для прочих —
|
|
821
|
+
текущее согласование графа в состоянии (`source: state` или `mixed`); нет
|
|
822
|
+
ни того ни другого — `source: none`, число неизвестно, а не ноль.
|
|
823
|
+
|
|
824
|
+
**Малые выборки и неизвестное.** `ReportMeasure` — `{value, n, unknown,
|
|
825
|
+
bound}`, `bound` — `exact | lower | upper | unknown`; неизвестное не
|
|
826
|
+
показывается нулём. Процент — только при знаменателе от 20, иначе «k of n».
|
|
827
|
+
Медиана и p75 — от 5 значений, иначе `null` и значения в `values`. Меньше 3
|
|
828
|
+
принятых поручений в окне — `summary.status: not-enough-data` (сырые
|
|
829
|
+
счётчики вместо заголовочных чисел). Сводка — не больше 5 чисел (принятые и
|
|
830
|
+
первая попытка, возвращено, срок, расход на принятое, отказы окружения),
|
|
831
|
+
каждое с предложением и основанием (`basis`). Раздел `limitations` есть
|
|
832
|
+
всегда: постоянные ограничения и найденные в данных (попытки без класса,
|
|
833
|
+
без замеров, без учёта вызовов, вызовы без цены, начало событий, смена
|
|
834
|
+
версии движка, усечения).
|
|
835
|
+
|
|
836
|
+
**Приватность и пределы.** В отчёт попадают только перечисленные поля: нет
|
|
837
|
+
prompt, вывода runtime, текстов находок, ошибок и причин, fencing-токенов.
|
|
838
|
+
Пути evidence — относительно `stateDir`; путь вне него — `…/<имя файла>`,
|
|
839
|
+
домашний каталог не печатается. `noTitles` убирает заголовки поручений и
|
|
840
|
+
метку проекта. Пределы (`REPORT_LIMITS`): 50 строк поручений (новые сверху),
|
|
841
|
+
50 ссылок evidence, 12 активных недель (ранние свёрнуты в `earlier`,
|
|
842
|
+
недели без активности — `gap`), 50 строк gates и стадий; JSON ≤ 512 КБ,
|
|
843
|
+
HTML ≤ 1 МБ. Усечение отмечено флагом и ограничением.
|
|
844
|
+
|
|
845
|
+
### HandoffPack
|
|
846
|
+
|
|
847
|
+
Пакет передачи контекста (`harness handoff`, `handoffPack(harness, options)`
|
|
848
|
+
и `handoffMarkdown(pack)` из корня пакета; `handoffVersion: 1`,
|
|
849
|
+
`handoffPackSchema`, `schemas/handoff-pack.schema.json`). Ведущий агент хоста,
|
|
850
|
+
который ведёт доску через много попыток, начинает новую сессию с пакета, а не
|
|
851
|
+
с пересказа предыдущей: факты собираются из хранилища теми же проекциями, что
|
|
852
|
+
`status --detail` и `explain`, и только читают состояние.
|
|
853
|
+
|
|
854
|
+
- `summary`, `limits` — счёт поручений по статусам, `maxAttempts` и
|
|
855
|
+
`repairBudget` политики;
|
|
856
|
+
- `queue`, `controller` — пауза выдачи, её причина и кто её снимает
|
|
857
|
+
(`queueStop`, `queuePause`), операция, держащая паузу (`operation`), и
|
|
858
|
+
классы отказа паузы runtime (`failures`); держатель роли controller и
|
|
859
|
+
свежесть срока;
|
|
860
|
+
- `active` — идущие попытки: стадия и её длительность, heartbeat, gates
|
|
861
|
+
текущей фазы (`attemptView`); `unfinished` — незакрытые записи попыток с
|
|
862
|
+
истёкшим владением или такие, которые поручение уже не ведёт;
|
|
863
|
+
- `works` — открытые поручения (идущие, упавшие, план, остальные): класс и
|
|
864
|
+
причина провала, удержание, эпизод восстановления с предложением,
|
|
865
|
+
блокировки (без общей паузы очереди; сверх предела — `blockersTruncated`) и
|
|
866
|
+
`next` — кто и что делает (по диагнозу `explain`; стадия и свойство — по
|
|
867
|
+
`nextAction`);
|
|
868
|
+
- `stops` — диагнозы `explain` без проб runtime, кроме `action: none`.
|
|
869
|
+
Остановка выдачи общей паузой очереди — одна запись с `queue: true` без
|
|
870
|
+
`workId`; одинаковые остановки на выдаче у разных поручений тоже
|
|
871
|
+
свёрнуты; `works` — первые 20 затронутых, `worksCount` — сколько всего.
|
|
872
|
+
Решения (`actor` lead или user и действие не `wait`) идут первыми;
|
|
873
|
+
- `failures` — последние провалившиеся и истёкшие попытки, новые первыми:
|
|
874
|
+
`failureKind`, код (`stopCodeOf`), текст ошибки и текущий статус
|
|
875
|
+
поручения (`workStatus`);
|
|
876
|
+
- `budgets` — общий бюджет и бюджеты групп (с `--graph` — только его
|
|
877
|
+
группа), бюджеты поручений — только с расходом или не в пределах:
|
|
878
|
+
сообщено (`reportedUsd`) и оценено (`estimatedUsd`) против предела, время,
|
|
879
|
+
`complete` и причины неполноты (вызовы без стоимости, незавершённые,
|
|
880
|
+
брошенные, попытки без учёта); при неполном расходе сумма — нижняя граница
|
|
881
|
+
(«≥ $X (неполно: …)» в Markdown), остаток — `null`. `repairs` —
|
|
882
|
+
восстановления незавершённых заданий графов;
|
|
883
|
+
- `next` — следующий шаг доски: первое решение; иначе идущая попытка со
|
|
884
|
+
свежим сроком владения — ждать (без controller — до `leaseUntil`); попытка
|
|
885
|
+
с истёкшим сроком или очередь без controller — `command: "harness run"` (run истечёт брошенную
|
|
886
|
+
попытку и продолжит очередь); пауза оператора — `"harness resume"`; иначе
|
|
887
|
+
первый открытый шаг поручения;
|
|
888
|
+
- `intentions` — единственный текст не из хранилища: намерения агента.
|
|
889
|
+
|
|
890
|
+
Пределы (`HANDOFF_LIMITS`): 50 открытых поручений, 30 остановок (после
|
|
891
|
+
свёртки) с 5 ссылками evidence каждая, 10 провалов, 20 незавершённых
|
|
892
|
+
попыток, 3 блокировки на поручение, 20 строк бюджетов, 10 заданий, 20
|
|
893
|
+
намерений по 1000 знаков. Тексты из хранилища и намерения очищаются от
|
|
894
|
+
escape-последовательностей терминала (ANSI CSI, OSC), серия управляющих
|
|
895
|
+
символов заменяется пробелом; строки фактов усечены до 300 знаков, имена и
|
|
896
|
+
идентификаторы — до 200, с «…» и без разрыва суррогатной пары. Пакет не
|
|
897
|
+
больше `HANDOFF_MAX_BYTES` (256 КБ UTF-8): сверх него записи отбрасываются в
|
|
898
|
+
порядке «намерения с конца, старые провалы, поручения без решения,
|
|
899
|
+
остановки без решения, незавершённые попытки, остальные поручения и
|
|
900
|
+
остановки, строки бюджетов» (`truncated.bySize`), отказа по размеру нет.
|
|
901
|
+
Сколько записей каждого списка не вошло — `truncated`; бюджеты поручений в
|
|
902
|
+
пределах и без расхода не показываются намеренно и считаются отдельно
|
|
903
|
+
(`budgetsWithin`), усечённые и отброшенные намерения — `intentions` и
|
|
904
|
+
`intentionsDropped`. Тексты из хранилища маскируются по значениям секретов
|
|
905
|
+
политики из окружения читающего процесса (`policySecrets`, как у
|
|
906
|
+
коннектора): секрет, которого в этом окружении нет, маска не знает —
|
|
907
|
+
библиотеке можно передать свою `redact`. Fencing-токены в пакет не
|
|
908
|
+
попадают.
|
|
909
|
+
|
|
910
|
+
Весь пакет — один снимок хранилища: `handoffPack` выполняет status,
|
|
911
|
+
диагнозы и чтение заданий графов внутри одного `read`
|
|
912
|
+
(`SqliteExecutionStore.read` вложенным чтением использует снимок внешнего,
|
|
913
|
+
без второго `BEGIN`). Попытка со свежим сроком владения без живого
|
|
914
|
+
controller — `next` «ждать до `leaseUntil` или проверить процесс-владелец»
|
|
915
|
+
без команды; `harness run` называется только для попытки с истёкшим сроком.
|
|
916
|
+
|
|
643
917
|
## Порты
|
|
644
918
|
|
|
645
919
|
| Порт | Договор |
|
|
@@ -771,36 +1045,116 @@ stdout — один JSON `CliEnvelope`: `{apiVersion, command, ok: true, data}`
|
|
|
771
1045
|
читающие на отсутствующем каталоге отвечают `NOT_FOUND` и ничего не создают.
|
|
772
1046
|
Бинарник не хранит настроек проекта и не помнит «последний активный проект».
|
|
773
1047
|
|
|
774
|
-
| Команда | Аргументы
|
|
775
|
-
| ------------------ |
|
|
776
|
-
| `validate` | `--graph F --policy F [--context F]`
|
|
777
|
-
| `review-plan` | `--state D --graph F --policy F --author A [--context F]`
|
|
778
|
-
| `review-contract` | `--state D --contract F --policy F --author A`
|
|
779
|
-
| `approve` | `--state D --subject ID --digest H`
|
|
780
|
-
| `run` | `--state D --graph F --policy F [--context F] [--sink file:D] [--once]`
|
|
781
|
-
| `status` | `--state D [--graph ID]`
|
|
782
|
-
| `events` | `--state D [--after N] [--limit 1–500]`
|
|
783
|
-
| `pause` | `--state D`
|
|
784
|
-
| `resume` | `--state D`
|
|
785
|
-
| `cancel` | `--state D --work ID [--reason T]`
|
|
786
|
-
| `retry` | `--state D --work ID [--reset --reason T]`
|
|
787
|
-
| `result` | `--state D --work ID`
|
|
788
|
-
| `deliver` | `--state D --work ID --sink file:D`
|
|
789
|
-
| `cleanup` | `--state D --run ID`
|
|
790
|
-
| `worktree-cleanup` | `--state D [--dry-run]`
|
|
791
|
-
| `profile` | `--profile ID\|./F [--repository D]`
|
|
792
|
-
| `doctor` | `[--state D] [--policy F]`
|
|
793
|
-
| `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]`
|
|
794
|
-
| `explain` | `--state D --policy F [--work ID]`
|
|
795
|
-
| `
|
|
796
|
-
| `
|
|
797
|
-
| `
|
|
798
|
-
|
|
|
1048
|
+
| Команда | Аргументы | Пишет | `data` | Повтор |
|
|
1049
|
+
| ------------------ | --------------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1050
|
+
| `validate` | `--graph F --policy F [--context F]` | нет | digests, число поручений | Чистая функция входов |
|
|
1051
|
+
| `review-plan` | `--state D --graph F --policy F --author A [--context F]` | да | `ReviewRecord` | Тот же digest и автор, уже согласованные, — тот же раунд без вызова модели; автор, не допускаемый правилом вендора, — `REVIEWER_SAME_VENDOR` до вызова |
|
|
1052
|
+
| `review-contract` | `--state D --contract F --policy F --author A` | да | `ReviewRecord` | Как `review-plan` |
|
|
1053
|
+
| `approve` | `--state D --subject ID --digest H` | да | subject, digest, at | Тот же digest — без изменений; только `approvalMode: operator` |
|
|
1054
|
+
| `run` | `--state D --graph F --policy F [--context F] [--sink file:D] [--once]` | да | граф, поручения и их блокеры, задание `workflow` | Та же редакция продолжает работу; другой digest той же редакции — `REVISION_CONFLICT` |
|
|
1055
|
+
| `status` | `--state D [--graph ID] [--detail]` | нет | очередь, графы, поручения с блокерами, бюджеты; с `--detail` — `detail` | Только чтение |
|
|
1056
|
+
| `events` | `--state D [--after N] [--limit 1–500]` | нет | события (неизвестный тип — `unknown`), `next` | Только чтение |
|
|
1057
|
+
| `pause` | `--state D` | да | `ControlState` | Без изменений |
|
|
1058
|
+
| `resume` | `--state D` | да | `ControlState` | Решение человека: снимает паузу оператора, штатной остановки и отказа runtime вместе с её классами; паузу операции reconfigure — `PAUSED` |
|
|
1059
|
+
| `cancel` | `--state D --work ID [--reason T]` | да | статус поручения | Отменённое — без изменений; это не retry |
|
|
1060
|
+
| `retry` | `--state D --work ID [--reset --reason T]` | да | статус поручения | В пределах `maxAttempts` и бюджета; `--reset` с причиной сбрасывает счётчик попыток, но не учёт расходов |
|
|
1061
|
+
| `result` | `--state D --work ID` | нет | `ResultEnvelope` | Только чтение |
|
|
1062
|
+
| `deliver` | `--state D --work ID --sink file:D` | да | `ResultEnvelope` | Доставленное не доставляется повторно; моделей и интеграции нет |
|
|
1063
|
+
| `cleanup` | `--state D --run ID` | да | исход очистки попытки |
|
|
1064
|
+
| `worktree-cleanup` | `--state D [--dry-run]` | да | счётчики и `worktrees[]` с действием и причиной отказа |
|
|
1065
|
+
| `profile` | `--profile ID\|./F [--repository D]` | нет | закрепление (`pin`) и разрешённый профиль | Чистая функция файлов профиля; команды проекта не исполняются |
|
|
1066
|
+
| `doctor` | `[--state D] [--policy F]` | нет | версии, runtime, sandbox, совместимость состояния и версии движка в нём | Без live-вызова модели |
|
|
1067
|
+
| `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]` | да | план файлов, `created`, `manifest`, `facts`, `toolchain`, `next` | Create-only `.harness/`, manifest до политики, политика последней; повтор — `created: []`; иное решение — `PATH_CONFLICT` |
|
|
1068
|
+
| `explain` | `--state D --policy F [--work ID]` | нет | `diagnoses[]` (`StopDiagnosis`) | Только чтение: без повторов, вызовов моделей и изменений состояния |
|
|
1069
|
+
| `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}` | Только чтение; те же данные и параметры — те же байты |
|
|
1070
|
+
| `handoff` | `--state D [--graph ID] [--intent T]… [--format json\|md]` | нет | `HandoffPack`; с `--format md` — Markdown без конверта | Только чтение; агент добавляет только намерения |
|
|
1071
|
+
| `plan-request` | `--brief F --policy F [--context F] [--contracts D] [--requirements [R:]F]… [--human]` | нет | `prompt`, `readOnly`, `recommendedTasks`, `maxTasks`, `basis`, `facts` (`PlanningFacts`) | Чистая функция входов: та же постановка и те же факты — тот же prompt и `basis`; модель не вызывается |
|
|
1072
|
+
| `plan-check` | `--draft F --policy F [--context F] [--contracts D] [--brief F [--basis H]]` | нет | `issues`, `checkPlan`; без проблем — `graph`, `graphDigest`, `basis` | Чистая функция входов и `HEAD` источников требований; согласования не выдаёт, gates не запускает; расхождение `--basis` — `APPROVAL_STALE` |
|
|
1073
|
+
| `capabilities` | — | нет | каталог общих операций (`OperationCatalog`) | Чистая функция установленной версии пакета |
|
|
1074
|
+
| `--version` | — | нет | версия пакета и API | — |
|
|
799
1075
|
|
|
800
1076
|
Полная форма каждой команды — `cliCommands` (аргументы, обязательность,
|
|
801
1077
|
идемпотентность, отказы exit 3). Все команды реализованы. `run` принимает `--author` (по умолчанию `external`) — автора графа для ревью плана. `HARNESS_CODEX_BIN` и `HARNESS_CLAUDE_BIN` подменяют исполняемые файлы runtime (fixture executables в тестах).
|
|
802
1078
|
`init --plan` ничего не пишет (exit 3 при конфликтах или неготовом toolchain). `--human` принимают только `init`, `explain` и `plan-request` (печатает prompt): успешный ответ — текст для человека, отказ — тот же JSON-конверт, exit code одинаков; у прочих команд флаг — `INVALID_INPUT`. `plan-check` с проблемами отвечает `ok: true` с данными, exit — по классу первой проблемы; draft — `schemas/plan-draft.schema.json` (`planDraftSchema`). Маршрут самостоятельного проекта и планирование — [standalone](standalone.md).
|
|
803
1079
|
|
|
1080
|
+
**`report`.** Читает каталог состояния только для чтения и строит
|
|
1081
|
+
`ValueReport` (`valueReport`); `binding.json` не нужен. Чтение однократное
|
|
1082
|
+
(`SqliteExecutionStore.readOnce`): база без журнала (`-wal`, `-journal`)
|
|
1083
|
+
открывается неизменяемой (`immutable=1`) — в каталоге не появляется ни одного
|
|
1084
|
+
файла; после чтения проверяется, что журнал не появился, а размер и время
|
|
1085
|
+
основного файла прежние, иначе (писатель начал работу или журнал уже был)
|
|
1086
|
+
чтение повторяется обычным открытием только для чтения. Долгоживущие
|
|
1087
|
+
дескрипторы (`status`, `events`, `result`, `explain`, `Harness.open` с
|
|
1088
|
+
`readOnlyState`) открываются обычным чтением: с блокировками SQLite они
|
|
1089
|
+
видят новые фиксации, а у WAL-базы появляются пустые служебные
|
|
1090
|
+
`-wal`/`-shm` (данных в них нет). `--format json` (по умолчанию) — обычный конверт. `--format
|
|
1091
|
+
md|html` — документированное исключение, как `--human`: успешный ответ
|
|
1092
|
+
печатается текстом без конверта (данные перед этим проверены схемой), отказ
|
|
1093
|
+
— тот же JSON-конверт и тот же exit code. `--out F` записывает отчёт
|
|
1094
|
+
выбранного формата во временный файл того же каталога и переименовывает
|
|
1095
|
+
его поверх цели (запись не идёт сквозь symlink или жёсткую ссылку; права
|
|
1096
|
+
прежнего файла сохраняются, новый — `0600`; при неполной записи временный
|
|
1097
|
+
файл удаляется);
|
|
1098
|
+
`PATH_CONFLICT` — цель не обычный файл, symlink, файл с несколькими жёсткими
|
|
1099
|
+
ссылками или путь внутри каталога состояния; отсутствующий каталог —
|
|
1100
|
+
`INVALID_INPUT`; stdout — конверт `{out, format, bytes, asOf}`. Неверное
|
|
1101
|
+
окно (`--since` не раньше `--until`, время без пояса) — `INVALID_INPUT`;
|
|
1102
|
+
нет каталога — `NOT_FOUND`, каталог не создаётся. Флаги `--since`,
|
|
1103
|
+
`--until`, `--as-of`, `--no-titles` принимает только `report` (`--format` — ещё
|
|
1104
|
+
`handoff`, со значениями json и md).
|
|
1105
|
+
Пределы размера (JSON 512 КБ, HTML и Markdown 1 МБ) проверяют сами
|
|
1106
|
+
`valueReport` и рендеры (`assertReportBytes`, `INTERNAL`).
|
|
1107
|
+
|
|
1108
|
+
**`handoff`.** Открывает каталог состояния только для чтения (политика — из
|
|
1109
|
+
`binding.json`, как у `status`) и строит `HandoffPack`. `--format json` (по
|
|
1110
|
+
умолчанию) — обычный конверт; `--format md` — документированное исключение,
|
|
1111
|
+
как у `report`: успешный ответ печатается Markdown без конверта. Отказ —
|
|
1112
|
+
JSON-конверт в обоих режимах; нет каталога — `NOT_FOUND`, каталог не
|
|
1113
|
+
создаётся; неизвестный `--graph` — `NOT_FOUND`; больше 20 `--intent` или
|
|
1114
|
+
`--format` не json/md — `INVALID_INPUT`. `--intent` принимает только
|
|
1115
|
+
`handoff`, `--format` — `report` и `handoff`.
|
|
1116
|
+
|
|
1117
|
+
**Причина отказа окружения `dependency-network`.** Установка зависимостей,
|
|
1118
|
+
упавшая на сети или реестре пакетов, получает класс `environment`, а не `gate`
|
|
1119
|
+
(правило — [архитектура](architecture.md#что-гарантируется), «Сеть и реестр при установке зависимостей»). Отдельного поля
|
|
1120
|
+
причины нет: схема состояния прежняя, а `failureKind` — `environment`.
|
|
1121
|
+
Причину несёт начало текста отказа: `<фаза>/<gate>: dependency-network: …` у
|
|
1122
|
+
gate, `dependency-network: … Шаг <id>: …` у шага `prepare`. Текст
|
|
1123
|
+
попадает в `WorkState.failure`, `AttemptState.error`, `summary` evidence gate и в
|
|
1124
|
+
`message` диагноза `explain` (`cause: environment`, `action: fix-environment`).
|
|
1125
|
+
У reviewer probe такой gate — `status: error`, `failure: environment`, `note`
|
|
1126
|
+
начинается с `dependency-network:`. Хост, который сам вызывает `runGate`,
|
|
1127
|
+
передаёт базу попытки в необязательном `GateRun.trustedBase`: без неё
|
|
1128
|
+
классификации нет и отказ остаётся `gate`. То же поле есть в описании probe
|
|
1129
|
+
(`trustedBase`).
|
|
1130
|
+
|
|
1131
|
+
**`status --detail`.** Без флага ответ `status` прежний. С флагом добавляется
|
|
1132
|
+
`detail: {at, queue, attempts}` — снимок наблюдателя по часам движка:
|
|
1133
|
+
|
|
1134
|
+
- `queue` — почему стоит выдача: `paused`, `reason` и `detail` (`queueStop`;
|
|
1135
|
+
у паузы отказа runtime `detail` — сообщение последнего отказа её классов),
|
|
1136
|
+
`since`, `operation`, `failures` (классы отказа паузы runtime) и кто и что её
|
|
1137
|
+
снимает — `code`, `cause`, `actor`, `action` (`queuePause`, то же
|
|
1138
|
+
рассуждение, что у `explain` на claim). Паузу, которую снимет следующий
|
|
1139
|
+
run (очередь ещё не запускали, штатная остановка, применимый запрос
|
|
1140
|
+
политики), `explain` считает снятой; `queue` показывает её с
|
|
1141
|
+
`liftedByRun: true` и тем же диагнозом, что у готового поручения в
|
|
1142
|
+
`explain`: `NOT_READY`, `not-ready`, `controller`, `wait`.
|
|
1143
|
+
- `attempts[]` — активные попытки (`attemptView`): `runId`, `workId`,
|
|
1144
|
+
`attempt`, `phase`, `runtime`, `model?`, `startedAt`, `elapsedMs`; `stage`
|
|
1145
|
+
— последний незакрытый замер (`name`, `family` — имя до `:`, `startedAt`,
|
|
1146
|
+
`elapsedMs`; при равном начале — позже записанный); `lease` — `owner`,
|
|
1147
|
+
`leaseUntil`, `leaseMs`, `sinceHeartbeatMs` (от последнего heartbeat,
|
|
1148
|
+
`leaseUntil − leaseMs`; нет при сроке `0` — владение отозвано) и `stale`
|
|
1149
|
+
(срок истёк). `leaseMs` — из политики процесса, который читает: у CLI —
|
|
1150
|
+
`binding.json` каталога состояния. `gates` — обязательные gates текущей фазы
|
|
1151
|
+
(интеграции в `integrating`, иначе кандидата) по последней записи каждого на
|
|
1152
|
+
текущем SHA фазы, без проверок потребителей: `passed + failed + remaining =
|
|
1153
|
+
required`.
|
|
1154
|
+
|
|
1155
|
+
`attemptView` и `queuePause` — чистые проекции `devcontour-harness/projections`:
|
|
1156
|
+
хост строит тот же вид по своей попытке.
|
|
1157
|
+
|
|
804
1158
|
**Общие операции и граница транспорта.** `init`, `explain`, `plan-request`,
|
|
805
1159
|
`plan-check` и `capabilities` — общие операции агентского слоя
|
|
806
1160
|
(`sharedOperations`): описание, `readOnly` (= `!writes`), вход (по `args`) и
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# devcontour-harness 0.1.0-alpha.30
|
|
2
|
+
|
|
3
|
+
Видно, что дал harness и что он делает сейчас: отчёт об эффекте по истории
|
|
4
|
+
работы, события стадий попытки и подробный `status`. Сетевые отказы установки
|
|
5
|
+
зависимостей больше не считаются дефектами проекта. Обязательные gates,
|
|
6
|
+
fencing и привязка доказательств к SHA не меняются; формат состояния прежний.
|
|
7
|
+
|
|
8
|
+
## Изменения
|
|
9
|
+
|
|
10
|
+
- **`harness report`.** Отчёт по каталогу состояния в JSON, Markdown или
|
|
11
|
+
одном HTML-файле без внешних ресурсов: принятые поручения и первая попытка,
|
|
12
|
+
возвраты проверками и ревью до merge, срок от согласования до приёмки,
|
|
13
|
+
расход на поручение, отказы окружения, недели и ограничения. Неизвестное
|
|
14
|
+
показано как «≥», «≤», диапазон или «неизвестно», а не ноль; на малых
|
|
15
|
+
выборках — «N из M» без процентов. Тот же отчёт — функция `valueReport`
|
|
16
|
+
(`devcontour-harness/report`, без `node:*`) для хоста. Отчёт только читает:
|
|
17
|
+
однократное чтение не оставляет файлов в каталоге состояния.
|
|
18
|
+
- **События стадий.** `attempt.stage` (`started`/`finished`) для каждой
|
|
19
|
+
измеряемой стадии попытки: хранилище зависимостей, подготовка, реализация,
|
|
20
|
+
каждый gate, ревью, интеграция. Пишутся в тех же fenced-транзакциях, что и
|
|
21
|
+
тайминги; стадия попытки, потерявшей lease, остаётся открытой до события
|
|
22
|
+
завершения попытки.
|
|
23
|
+
- **`status --detail`.** Текущая стадия и время активных попыток, свежесть
|
|
24
|
+
lease, счёт обязательных gates текущей фазы и вид остановки очереди — тем же
|
|
25
|
+
рассуждением, что и `explain`. Проекция `attemptView` для хостов.
|
|
26
|
+
- **Чтение незнакомых событий.** События неизвестного типа читаются как
|
|
27
|
+
`unknown`, а не ломают `events`. Тип `RunEvent` включает этот вариант: код,
|
|
28
|
+
читающий `payload`, сужает по `type` или использует `KnownRunEvent`.
|
|
29
|
+
- **Сеть и реестр при установке зависимостей.** Упавшая установка — отказ
|
|
30
|
+
среды с причиной `dependency-network`, только если команда — установка из
|
|
31
|
+
политики, входы менеджера пакетов совпадают с базой попытки, база не
|
|
32
|
+
исполняет кода при установке, менеджер вышел сам и назвал только сетевые
|
|
33
|
+
коды. Всё, что изменил кандидат, остаётся провалом проверки.
|
|
34
|
+
|
|
35
|
+
## Обновление
|
|
36
|
+
|
|
37
|
+
Пакет alpha.29 остаётся неизменным. Формат состояния (`stateVersion: 1`) и
|
|
38
|
+
политики прежний. Откат ниже этой версии не прочитает страницу событий с
|
|
39
|
+
`attempt.stage`: откатывайтесь вместе с копией состояния, снятой до
|
|
40
|
+
обновления. Подробнее — `docs/upgrade.md`.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# devcontour-harness 0.1.0-alpha.31
|
|
2
|
+
|
|
3
|
+
Controller сам замечает зависшие попытки и проверки, не дожидаясь вопроса
|
|
4
|
+
человека, а новая сессия ведущего агента начинает с пакета передачи из
|
|
5
|
+
хранилища, а не с пересказа прошлой. Обязательные gates, fencing и привязка
|
|
6
|
+
доказательств к SHA не меняются; `stateVersion` и `policyVersion` прежние.
|
|
7
|
+
|
|
8
|
+
## Изменения
|
|
9
|
+
|
|
10
|
+
- **Обход зависаний.** Controller, ведущий очередь, раз в
|
|
11
|
+
`stallSweep.intervalMs` оценивает исполняющиеся попытки: вывод, начало и
|
|
12
|
+
конец команд, границы стадий и прирост процессорного времени дерева
|
|
13
|
+
процессов. Состояния `active` → `quiet` → `stalled` пишутся в
|
|
14
|
+
`AttemptState.liveness` и событием `attempt.liveness` под fencing; у
|
|
15
|
+
совместной проверки — `joint.liveness`, у `runGatesAt` — `onLiveness` и
|
|
16
|
+
`liveness[]` результата. Цикл ожидания, рождающий процессы без прогресса,
|
|
17
|
+
движением не считается. На `stalled` — снимок процессов (команды под маской
|
|
18
|
+
среды) и хвост вывода в `artifacts/<runId>/stall-<эпизод>.json`.
|
|
19
|
+
- **Политика `stallSweep`.** `{intervalMs, quietMs, stalledMs, action}`;
|
|
20
|
+
без поля — 30 с / 3 мин / 10 мин и `report` (только сообщить). `stop`
|
|
21
|
+
останавливает попытку отказом нового класса `stalled`: повтор или правка
|
|
22
|
+
среды, а не правка кода (`repairPolicy.stalled`). Поле — надзор, в digest
|
|
23
|
+
исполнения не входит: основания попыток и reuse не меняются.
|
|
24
|
+
- **Живость в `status`, `status --detail` и `explain`.** `works[].liveness`
|
|
25
|
+
у активной попытки без движения, `detail.attempts[].liveness`, причина
|
|
26
|
+
`stalled` у работающего поручения с действием человека или controller.
|
|
27
|
+
- **`harness handoff`.** Пакет передачи контекста из одного снимка
|
|
28
|
+
хранилища: активные и незавершённые попытки, открытые поручения со
|
|
29
|
+
следующим шагом, остановки (решения первыми), последние провалы, бюджеты и
|
|
30
|
+
следующий шаг доски; агент добавляет только намерения (`--intent`). JSON
|
|
31
|
+
по умолчанию, `--format md` — Markdown; `--graph` сужает до одного графа.
|
|
32
|
+
Размер ограничен 256 КБ с отбрасыванием записей по порядку важности,
|
|
33
|
+
тексты очищены от управляющих последовательностей и маскируются по
|
|
34
|
+
секретам политики. Библиотека: `handoffPack`, `handoffMarkdown`,
|
|
35
|
+
`handoffPackSchema`, схема `schemas/handoff-pack.schema.json`.
|
|
36
|
+
- **Вложенное чтение хранилища.** `SqliteExecutionStore.read` внутри другого
|
|
37
|
+
`read` использует снимок внешнего, без второго `BEGIN`.
|
|
38
|
+
|
|
39
|
+
## Обновление
|
|
40
|
+
|
|
41
|
+
Пакет alpha.30 остаётся неизменным. Обход включён по умолчанию (`report`),
|
|
42
|
+
поэтому первая же затихшая попытка запишет `liveness` в документ состояния, а
|
|
43
|
+
alpha.30 и ниже такой документ не прочитают. Откатывайтесь вместе с копией
|
|
44
|
+
состояния, снятой до обновления. Подробнее — `docs/upgrade.md`.
|