devcontour-harness 0.1.0-alpha.30 → 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.
Files changed (75) hide show
  1. package/README.md +23 -15
  2. package/docs/contracts.md +138 -2
  3. package/docs/release-notes/0.1.0-alpha.31.md +44 -0
  4. package/docs/upgrade.md +44 -0
  5. package/lib/agents/cli-adapter.js +1 -0
  6. package/lib/cli.js +23 -1
  7. package/lib/contracts/cli.d.ts +1077 -4
  8. package/lib/contracts/cli.js +43 -1
  9. package/lib/contracts/diagnosis.d.ts +2 -1
  10. package/lib/contracts/diagnosis.js +1 -0
  11. package/lib/contracts/events.d.ts +414 -5
  12. package/lib/contracts/events.js +46 -1
  13. package/lib/contracts/execution.d.ts +112 -1
  14. package/lib/contracts/execution.js +38 -0
  15. package/lib/contracts/handoff.d.ts +694 -0
  16. package/lib/contracts/handoff.js +291 -0
  17. package/lib/contracts/index.d.ts +1 -0
  18. package/lib/contracts/index.js +1 -0
  19. package/lib/contracts/policy.d.ts +27 -1
  20. package/lib/contracts/policy.js +38 -2
  21. package/lib/contracts/published.d.ts +841 -2
  22. package/lib/contracts/published.js +2 -0
  23. package/lib/contracts/repair-policy.js +5 -0
  24. package/lib/contracts/report.d.ts +2 -0
  25. package/lib/control/harness.d.ts +37 -11
  26. package/lib/control/harness.js +3 -0
  27. package/lib/control/recovery.d.ts +1 -1
  28. package/lib/engine/engine.d.ts +15 -7
  29. package/lib/engine/engine.js +24 -0
  30. package/lib/engine/joint-runner.d.ts +6 -0
  31. package/lib/engine/joint-runner.js +20 -4
  32. package/lib/engine/property-recovery.js +1 -0
  33. package/lib/engine/reuse.js +1 -0
  34. package/lib/engine/runner.d.ts +8 -0
  35. package/lib/engine/runner.js +116 -11
  36. package/lib/engine/stall-sweep.d.ts +137 -0
  37. package/lib/engine/stall-sweep.js +393 -0
  38. package/lib/environment/activity.d.ts +34 -0
  39. package/lib/environment/activity.js +55 -0
  40. package/lib/environment/lifecycle.js +1 -0
  41. package/lib/environment/process.d.ts +7 -1
  42. package/lib/environment/process.js +14 -0
  43. package/lib/environment/redaction.d.ts +2 -0
  44. package/lib/environment/redaction.js +19 -0
  45. package/lib/explain/state.d.ts +1 -1
  46. package/lib/explain/state.js +12 -0
  47. package/lib/handoff/index.d.ts +2 -0
  48. package/lib/handoff/index.js +3 -0
  49. package/lib/handoff/markdown.d.ts +6 -0
  50. package/lib/handoff/markdown.js +153 -0
  51. package/lib/handoff/pack.d.ts +49 -0
  52. package/lib/handoff/pack.js +492 -0
  53. package/lib/index.d.ts +2 -1
  54. package/lib/index.js +1 -0
  55. package/lib/integrations/connector/redact.d.ts +2 -13
  56. package/lib/integrations/connector/redact.js +2 -21
  57. package/lib/projections/attempt.d.ts +28 -0
  58. package/lib/projections/attempt.js +14 -0
  59. package/lib/projections/stop.d.ts +11 -1
  60. package/lib/projections/stop.js +29 -0
  61. package/lib/report/compute.js +1 -0
  62. package/lib/storage/document.d.ts +28 -6
  63. package/lib/storage/sqlite.d.ts +2 -0
  64. package/lib/storage/sqlite.js +9 -1
  65. package/lib/verification/gates-at.d.ts +11 -1
  66. package/lib/verification/gates-at.js +28 -2
  67. package/lib/verification/gates.d.ts +3 -1
  68. package/lib/verification/gates.js +5 -0
  69. package/package.json +1 -1
  70. package/schemas/execution-document.schema.json +68 -0
  71. package/schemas/execution-policy.schema.json +32 -0
  72. package/schemas/handoff-pack.schema.json +1424 -0
  73. package/schemas/run-event.schema.json +360 -0
  74. package/schemas/stop-diagnosis.schema.json +1 -0
  75. package/schemas/value-report.schema.json +1 -0
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.30` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.31` — предварительный выпуск (alpha). Договоры
9
9
  > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
10
10
  > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
11
11
  > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
28
28
  Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
29
29
 
30
30
  ```sh
31
- npm install --save-exact devcontour-harness@0.1.0-alpha.30 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.31 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -90,19 +90,20 @@ git rev-parse refs/heads/harness/accepted # совпадает с data.result.
90
90
 
91
91
  ## Команды
92
92
 
93
- | Команда | Что делает |
94
- | -------------------------------------------- | -------------------------------------------------- |
95
- | `validate --graph F --policy F` | Проверка входов без моделей и записи |
96
- | `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
97
- | `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
98
- | `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
99
- | `status / events / result --state D` | Чтение без побочных эффектов |
100
- | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
- | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
- | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
103
- | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
104
- | `doctor` | Версии, runtime, sandbox, совместимость состояния |
105
- | `report --state D [--format md\|html]` | Отчёт об эффекте по данным проекта |
93
+ | Команда | Что делает |
94
+ | ----------------------------------------------- | -------------------------------------------------- |
95
+ | `validate --graph F --policy F` | Проверка входов без моделей и записи |
96
+ | `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
97
+ | `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
98
+ | `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
99
+ | `status / events / result --state D` | Чтение без побочных эффектов |
100
+ | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
+ | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
+ | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
103
+ | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
104
+ | `doctor` | Версии, runtime, sandbox, совместимость состояния |
105
+ | `report --state D [--format md\|html]` | Отчёт об эффекте по данным проекта |
106
+ | `handoff --state D [--format md] [--intent T]…` | Пакет передачи контекста новой сессии агента |
106
107
 
107
108
  stdout — один JSON (`devcontour-harness/v1alpha1`), диагностика — stderr. Exit
108
109
  codes: 0 успех, 2 неверный вход, 3 отказ/блокировка, 4 инфраструктура.
@@ -146,6 +147,13 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
146
147
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
147
148
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
148
149
 
150
+ ## Выпуск 0.1.0-alpha.31
151
+
152
+ Controller сам замечает зависшие попытки и проверки (`stallSweep`, отказ
153
+ `stalled`), а `harness handoff` собирает пакет передачи контекста новой сессии
154
+ агента из хранилища.
155
+ Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.31.md).
156
+
149
157
  ## Выпуск 0.1.0-alpha.30
150
158
 
151
159
  Отчёт об эффекте `harness report`, события стадий и `status --detail` для
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,12 @@ 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
+
637
690
  `finished` может не прийти: поздний finish владельца, утратившего срок,
638
691
  отклоняется (runner его не повторяет), упавший процесс его не пишет, а `adopt`
639
692
  и recovery открытые замеры прежнего владельца не закрывают. Такая стадия
@@ -789,6 +842,78 @@ prompt, вывода runtime, текстов находок, ошибок и п
789
842
  недели без активности — `gap`), 50 строк gates и стадий; JSON ≤ 512 КБ,
790
843
  HTML ≤ 1 МБ. Усечение отмечено флагом и ограничением.
791
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
+
792
917
  ## Порты
793
918
 
794
919
  | Порт | Договор |
@@ -942,6 +1067,7 @@ stdout — один JSON `CliEnvelope`: `{apiVersion, command, ok: true, data}`
942
1067
  | `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]` | да | план файлов, `created`, `manifest`, `facts`, `toolchain`, `next` | Create-only `.harness/`, manifest до политики, политика последней; повтор — `created: []`; иное решение — `PATH_CONFLICT` |
943
1068
  | `explain` | `--state D --policy F [--work ID]` | нет | `diagnoses[]` (`StopDiagnosis`) | Только чтение: без повторов, вызовов моделей и изменений состояния |
944
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 без конверта | Только чтение; агент добавляет только намерения |
945
1071
  | `plan-request` | `--brief F --policy F [--context F] [--contracts D] [--requirements [R:]F]… [--human]` | нет | `prompt`, `readOnly`, `recommendedTasks`, `maxTasks`, `basis`, `facts` (`PlanningFacts`) | Чистая функция входов: та же постановка и те же факты — тот же prompt и `basis`; модель не вызывается |
946
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` |
947
1073
  | `capabilities` | — | нет | каталог общих операций (`OperationCatalog`) | Чистая функция установленной версии пакета |
@@ -974,10 +1100,20 @@ md|html` — документированное исключение, как `--
974
1100
  `INVALID_INPUT`; stdout — конверт `{out, format, bytes, asOf}`. Неверное
975
1101
  окно (`--since` не раньше `--until`, время без пояса) — `INVALID_INPUT`;
976
1102
  нет каталога — `NOT_FOUND`, каталог не создаётся. Флаги `--since`,
977
- `--until`, `--as-of`, `--format`, `--no-titles` принимает только `report`.
1103
+ `--until`, `--as-of`, `--no-titles` принимает только `report` (`--format` — ещё
1104
+ `handoff`, со значениями json и md).
978
1105
  Пределы размера (JSON 512 КБ, HTML и Markdown 1 МБ) проверяют сами
979
1106
  `valueReport` и рендеры (`assertReportBytes`, `INTERNAL`).
980
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
+
981
1117
  **Причина отказа окружения `dependency-network`.** Установка зависимостей,
982
1118
  упавшая на сети или реестре пакетов, получает класс `environment`, а не `gate`
983
1119
  (правило — [архитектура](architecture.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`.
package/docs/upgrade.md CHANGED
@@ -313,6 +313,50 @@ install|fetch` или `yarn install`;
313
313
  возвращается прежняя классификация; уже записанные попытки сохраняют свой
314
314
  класс.
315
315
 
316
+ ### alpha.31: обход зависаний
317
+
318
+ Номера форматов прежние (`stateVersion: 1`, `policyVersion: 1`), новое —
319
+ аддитивно:
320
+
321
+ - **Состояние.** Необязательное поле `AttemptState.liveness` (`state`, `at`,
322
+ `lastMovementAt`, `activity`, `action`, `artifact`) и класс отказа
323
+ `stalled` в `failureKind`. Поле пишется только на переходах живости.
324
+ - **Политика.** Необязательное поле
325
+ `stallSweep{intervalMs, quietMs, stalledMs, action}` и
326
+ `repairPolicy.stalled`. Без поля обход идёт с
327
+ умолчаниями (30 000 / 180 000 / 600 000 мс, `report`); умолчание в
328
+ политику не подставляется, digest политики и digest исполнения прежние,
329
+ поэтому основания попыток и reuse кандидатов после обновления не меняются.
330
+ - **Журнал.** События `attempt.liveness` и `joint.liveness`. Файлы снимков
331
+ `artifacts/<runId>/stall-<эпизод>.json` в каталоге состояния.
332
+ - **Хост.** `runGatesAt` принимает `onLiveness` и возвращает `liveness[]`;
333
+ `status` — `works[].liveness`, `status --detail` —
334
+ `detail.attempts[].liveness`.
335
+
336
+ **Откат.** Документ состояния и политика разбираются строго: alpha.30 и ниже
337
+ отказывают на документе, где у попытки есть `liveness` или отказ `stalled`, и
338
+ на политике с `stallSweep`. Обход включён по умолчанию, поэтому такой документ
339
+ появляется с первой затихшей попыткой. Путь — строка «Новая версия уже
340
+ изменила формат» таблицы [«Откат»](#откат): остановить writers, восстановить
341
+ копию каталога состояния, снятую до обновления, вместе с прежней версией
342
+ пакета и убрать `stallSweep` из политики. События `attempt.liveness` alpha.30
343
+ читает как `unknown`.
344
+
345
+ ### alpha.31: пакет передачи контекста
346
+
347
+ Только чтение: формат состояния, политики и событий не меняется. Новое —
348
+ команда
349
+ `harness handoff --state D [--graph ID] [--intent T]… [--format json|md]`,
350
+ функции `handoffPack` и `handoffMarkdown` и схема
351
+ `handoffPackSchema` (`schemas/handoff-pack.schema.json`, `handoffVersion: 1`)
352
+ из корня пакета. `handoffPack` вызывает `read` хранилища вложенно;
353
+ `SqliteExecutionStore` во вложенном чтении использует снимок внешнего, без
354
+ второго `BEGIN`. Хранилище хоста со своим `read` должно допускать вложенный
355
+ вызов.
356
+
357
+ **Откат.** Ниже этой версии команды `handoff` нет; состояние она не меняла,
358
+ поэтому откат пакета копии не требует.
359
+
316
360
  ## Перед обновлением
317
361
 
318
362
  1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
@@ -296,6 +296,7 @@ export function cliAdapter(runtime, options = {}) {
296
296
  const telemetry = usageStream(runtime);
297
297
  try {
298
298
  result = await command(argv, r.cwd, {
299
+ activity: { kind: 'agent', label: `${runtime} ${r.task}`.slice(0, 300) },
299
300
  contain: { dirs: review ? [] : r.sandbox.writable },
300
301
  onRawStdout: (text) => {
301
302
  telemetry.push(text);
package/lib/cli.js CHANGED
@@ -25,6 +25,7 @@ import { SqliteExecutionStore } from "./storage/sqlite.js";
25
25
  import { collectReportInput } from "./control/report.js";
26
26
  import { writeReportFile } from "./control/report-file.js";
27
27
  import { valueReport, reportHtml, reportMarkdown } from "./report/index.js";
28
+ import { handoffMarkdown, handoffPack } from "./handoff/index.js";
28
29
  const usage = `harness ${HARNESS_VERSION}
29
30
 
30
31
  Использование: harness <команда> [параметры]
@@ -221,6 +222,7 @@ const options = {
221
222
  'as-of': { type: 'string' },
222
223
  format: { type: 'string' },
223
224
  'no-titles': { type: 'boolean' },
225
+ intent: { type: 'string', multiple: true },
224
226
  };
225
227
  /** Новые флаги H1 допустимы только у своих команд; прежние команды их не принимают. */
226
228
  const flagOwners = {
@@ -237,8 +239,9 @@ const flagOwners = {
237
239
  since: ['report'],
238
240
  until: ['report'],
239
241
  'as-of': ['report'],
240
- format: ['report'],
242
+ format: ['report', 'handoff'],
241
243
  'no-titles': ['report'],
244
+ intent: ['handoff'],
242
245
  };
243
246
  /** Явное человеческое представление успешного ответа (`--human`). */
244
247
  const presenters = {
@@ -629,6 +632,25 @@ async function run(argv) {
629
632
  data: { out: v.out, format, bytes: Buffer.byteLength(text), asOf: report.window.asOf },
630
633
  };
631
634
  }
635
+ case 'handoff': {
636
+ const format = v.format ?? 'json';
637
+ if (format !== 'json' && format !== 'md')
638
+ throw new HarnessError('INVALID_INPUT', '--format: для handoff ожидается json или md', [
639
+ { path: ['--format'], message: format },
640
+ ]);
641
+ const h = open(need('state'), binding(need('state')), 'state');
642
+ try {
643
+ const data = handoffPack(h, {
644
+ ...optional('graphId', v.graph),
645
+ ...optional('intentions', v.intent),
646
+ });
647
+ // JSON-конверт по умолчанию; --format md — текст, как у report. Отказ — JSON.
648
+ return { command, data, ...(format === 'md' ? { text: handoffMarkdown(data) } : {}) };
649
+ }
650
+ finally {
651
+ h.close();
652
+ }
653
+ }
632
654
  case 'plan-request': {
633
655
  const b = loadPolicy(need('policy'));
634
656
  const first = b.policy.repositories[0]?.id ?? 'main';