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.
Files changed (103) hide show
  1. package/README.md +50 -14
  2. package/docs/architecture.md +64 -0
  3. package/docs/compatibility.md +15 -14
  4. package/docs/contracts.md +380 -26
  5. package/docs/release-notes/0.1.0-alpha.30.md +40 -0
  6. package/docs/release-notes/0.1.0-alpha.31.md +44 -0
  7. package/docs/review-probes.md +17 -17
  8. package/docs/upgrade.md +137 -0
  9. package/lib/agents/cli-adapter.js +1 -0
  10. package/lib/agents/review-probe.d.ts +1 -0
  11. package/lib/agents/review-probe.js +20 -0
  12. package/lib/cli.js +79 -1
  13. package/lib/contracts/cli.d.ts +2216 -15
  14. package/lib/contracts/cli.js +171 -4
  15. package/lib/contracts/diagnosis.d.ts +2 -1
  16. package/lib/contracts/diagnosis.js +1 -0
  17. package/lib/contracts/events.d.ts +1052 -4
  18. package/lib/contracts/events.js +94 -1
  19. package/lib/contracts/execution.d.ts +112 -1
  20. package/lib/contracts/execution.js +38 -0
  21. package/lib/contracts/handoff.d.ts +694 -0
  22. package/lib/contracts/handoff.js +291 -0
  23. package/lib/contracts/index.d.ts +2 -0
  24. package/lib/contracts/index.js +2 -0
  25. package/lib/contracts/policy.d.ts +27 -1
  26. package/lib/contracts/policy.js +38 -2
  27. package/lib/contracts/ports.d.ts +5 -1
  28. package/lib/contracts/published.d.ts +1398 -2
  29. package/lib/contracts/published.js +4 -0
  30. package/lib/contracts/repair-policy.js +5 -0
  31. package/lib/contracts/report.d.ts +1151 -0
  32. package/lib/contracts/report.js +401 -0
  33. package/lib/control/harness.d.ts +486 -7
  34. package/lib/control/harness.js +86 -1
  35. package/lib/control/recovery.d.ts +1 -1
  36. package/lib/control/report-file.d.ts +19 -0
  37. package/lib/control/report-file.js +85 -0
  38. package/lib/control/report.d.ts +9 -0
  39. package/lib/control/report.js +27 -0
  40. package/lib/engine/engine.d.ts +20 -8
  41. package/lib/engine/engine.js +73 -7
  42. package/lib/engine/joint-runner.d.ts +6 -0
  43. package/lib/engine/joint-runner.js +20 -4
  44. package/lib/engine/property-recovery.js +1 -0
  45. package/lib/engine/reuse.js +1 -0
  46. package/lib/engine/runner.d.ts +8 -0
  47. package/lib/engine/runner.js +121 -13
  48. package/lib/engine/stall-sweep.d.ts +137 -0
  49. package/lib/engine/stall-sweep.js +393 -0
  50. package/lib/environment/activity.d.ts +34 -0
  51. package/lib/environment/activity.js +55 -0
  52. package/lib/environment/dependency-network.d.ts +42 -0
  53. package/lib/environment/dependency-network.js +413 -0
  54. package/lib/environment/lifecycle.d.ts +3 -1
  55. package/lib/environment/lifecycle.js +23 -4
  56. package/lib/environment/process.d.ts +12 -1
  57. package/lib/environment/process.js +52 -0
  58. package/lib/environment/redaction.d.ts +2 -0
  59. package/lib/environment/redaction.js +19 -0
  60. package/lib/explain/state.d.ts +38 -0
  61. package/lib/explain/state.js +31 -11
  62. package/lib/handoff/index.d.ts +2 -0
  63. package/lib/handoff/index.js +3 -0
  64. package/lib/handoff/markdown.d.ts +6 -0
  65. package/lib/handoff/markdown.js +153 -0
  66. package/lib/handoff/pack.d.ts +49 -0
  67. package/lib/handoff/pack.js +492 -0
  68. package/lib/index.d.ts +4 -1
  69. package/lib/index.js +3 -0
  70. package/lib/integrations/connector/redact.d.ts +2 -13
  71. package/lib/integrations/connector/redact.js +2 -21
  72. package/lib/projections/attempt.d.ts +129 -0
  73. package/lib/projections/attempt.js +78 -0
  74. package/lib/projections/index.d.ts +2 -1
  75. package/lib/projections/index.js +2 -1
  76. package/lib/projections/stop.d.ts +30 -1
  77. package/lib/projections/stop.js +59 -24
  78. package/lib/report/compute.d.ts +72 -0
  79. package/lib/report/compute.js +1220 -0
  80. package/lib/report/document.d.ts +27 -0
  81. package/lib/report/document.js +206 -0
  82. package/lib/report/format.d.ts +23 -0
  83. package/lib/report/format.js +53 -0
  84. package/lib/report/html.d.ts +7 -0
  85. package/lib/report/html.js +109 -0
  86. package/lib/report/index.d.ts +4 -0
  87. package/lib/report/index.js +7 -0
  88. package/lib/report/markdown.d.ts +7 -0
  89. package/lib/report/markdown.js +112 -0
  90. package/lib/storage/document.d.ts +28 -6
  91. package/lib/storage/sqlite.d.ts +21 -0
  92. package/lib/storage/sqlite.js +70 -7
  93. package/lib/verification/gates-at.d.ts +11 -1
  94. package/lib/verification/gates-at.js +28 -2
  95. package/lib/verification/gates.d.ts +9 -1
  96. package/lib/verification/gates.js +20 -0
  97. package/package.json +5 -1
  98. package/schemas/execution-document.schema.json +68 -0
  99. package/schemas/execution-policy.schema.json +32 -0
  100. package/schemas/handoff-pack.schema.json +1424 -0
  101. package/schemas/run-event.schema.json +455 -0
  102. package/schemas/stop-diagnosis.schema.json +1 -0
  103. package/schemas/value-report.schema.json +2542 -0
@@ -75,14 +75,14 @@ To run a declared gate, call run_check with exactly {"gate":"domain"}, {"gate":"
75
75
 
76
76
  ## Статусы
77
77
 
78
- | `status` | `failure` | Смысл |
79
- | ------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
- | `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
81
- | `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
82
- | `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
83
- | `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет песочницы, песочница не запустила команду |
84
- | `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
85
- | `budget-exhausted`, `rejected` | — | команда не запускалась |
78
+ | `status` | `failure` | Смысл |
79
+ | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
80
+ | `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
81
+ | `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
82
+ | `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
83
+ | `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, установка зависимостей упала на сети или реестре (`dependency-network`), нет песочницы, песочница не запустила команду |
84
+ | `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
85
+ | `budget-exhausted`, `rejected` | — | команда не запускалась |
86
86
 
87
87
  Ошибка среды и ошибка отчёта — не находка в коде; находка, сославшаяся на запуск с
88
88
  `failure: environment`, не получает `observed`.
@@ -115,15 +115,15 @@ target ref.
115
115
  команду, когда весь stderr — только строки известного отказа запуска srt (`Error: Shell '…' not
116
116
  found in PATH`, `Failed to execute command: …`), даёт `error`/`environment`.
117
117
 
118
- | Событие | В `commands` |
119
- | ----------------------------------------------------------------------------------------- | ------------ |
120
- | Команда завершилась с любым кодом | да |
121
- | `timeout`/`cancelled` после старта (код `null`, частичный вывод) | да |
122
- | `error`/`environment` после старта (сеть закрыта песочницей, EPERM, сбой записи evidence) | да |
123
- | `failed`/`report`: код 0, JUnit отсутствует или испорчен | да |
124
- | Неизвестный gate, бюджет исчерпан, нет executable, отказ песочницы или scratch до старта | нет |
125
- | Вызов отменён до запуска (`cancelled`, команда не исполнялась) | нет |
126
- | Только резерв `start`, `abandoned`, битая строка, объект без формы исхода | нет |
118
+ | Событие | В `commands` |
119
+ | --------------------------------------------------------------------------------------------------------------- | ------------ |
120
+ | Команда завершилась с любым кодом | да |
121
+ | `timeout`/`cancelled` после старта (код `null`, частичный вывод) | да |
122
+ | `error`/`environment` после старта (сеть закрыта песочницей, `dependency-network`, EPERM, сбой записи evidence) | да |
123
+ | `failed`/`report`: код 0, JUnit отсутствует или испорчен | да |
124
+ | Неизвестный gate, бюджет исчерпан, нет executable, отказ песочницы или scratch до старта | нет |
125
+ | Вызов отменён до запуска (`cancelled`, команда не исполнялась) | нет |
126
+ | Только резерв `start`, `abandoned`, битая строка, объект без формы исхода | нет |
127
127
 
128
128
  Незасчитанные записи перечислены в `inspection.excluded` с причиной; полная диагностика — в
129
129
  `review.json.probes` и журнале.
package/docs/upgrade.md CHANGED
@@ -220,6 +220,143 @@ setgid или sticky — отказ (pnpm таких не создаёт). От
220
220
  версии, seeds и копии подходят обеим. Подробнее —
221
221
  [хранилище зависимостей](toolchains.md#хранилище-зависимостей).
222
222
 
223
+ ### alpha.30: события стадий
224
+
225
+ Форматы состояния (`stateVersion: 1`), политики и её digest прежние: в
226
+ документ состояния не добавлено ни одного поля. Новое в журнале и в CLI:
227
+
228
+ - **Терпимое чтение событий.** Событие типа, которого версия не знает
229
+ (записанное более новой версией), `events` и `ExecutionStore.events`
230
+ возвращают непрозрачным: конверт без нагрузки, `type: 'unknown'` и исходный
231
+ тип в `original` — а не обрывают список отказом. Писатель строгий: событие
232
+ `unknown` не записывается. Известный тип с нарушенной нагрузкой — по-прежнему
233
+ отказ. Хост, который сам разбирает сохранённые события, использует
234
+ `readRunEvent`. В TypeScript `RunEvent` теперь включает `UnknownRunEvent`:
235
+ код, читающий `payload` без сужения по `type`, перестаёт компилироваться —
236
+ сузить (`e.type !== 'unknown'` или конкретный тип) либо взять
237
+ `KnownRunEvent`. Тип `ExecutionStore.events()` прежний: хранилища хоста не
238
+ меняются.
239
+ - **Событие `attempt.stage`.** На каждую стадию попытки (замер
240
+ `AttemptState.timings`) — одно `started` и не больше одного `finished` с
241
+ `durationMs` и исходом, в той же транзакции под fencing, что и замер.
242
+ Стадия попытки, утратившей владение или упавшей, остаётся открытой; её
243
+ конец — событие конца попытки.
244
+ - **`status --detail`.** Поле `detail`: почему стоит выдача и активные
245
+ попытки — стадия и её длительность, владение и его свежесть, счёт gates.
246
+ Без флага ответ `status` прежний.
247
+
248
+ **Откат.** Прежние версии (alpha.29 и ниже) разбирают каждое событие строго:
249
+ терпимое чтение появляется только с этой версией. После отката ниже неё
250
+ `harness events` и чтение журнала хостом через прежний `ExecutionStore.events`
251
+ отказывают на первой странице, где есть `attempt.stage`; документ состояния,
252
+ `status`, `result` и работа очереди читаются как прежде. Рекомендуемый путь —
253
+ строка «Новая версия уже изменила формат» таблицы [«Откат»](#откат): остановить
254
+ writers и восстановить копию каталога состояния, снятую до обновления, вместе
255
+ с прежней версией пакета. Без копии прежняя версия продолжает работу очереди,
256
+ но журнал после первого `attempt.stage` ей не прочитать; удалять или
257
+ переписывать события ради неё нельзя.
258
+
259
+ ### alpha.30: отчёт об эффекте
260
+
261
+ Форматы состояния (`stateVersion: 1`), политики, событий и их схем прежние:
262
+ отчёт только читает. Новое — аддитивно:
263
+
264
+ - **`harness report`.** Отчёт по каталогу состояния: принятые поручения и
265
+ первая попытка, возвраты проверками и ревью, действия человека (нижняя
266
+ граница), срок от согласования до приёмки, расход (неизвестная цена —
267
+ «≥», а не ноль), отказы окружения, недели и ограничения. `--format
268
+ json|md|html`, `--out F`, окно `--since/--until`, `--as-of`, `--no-titles`.
269
+ База открывается только для чтения; `binding.json` не нужен.
270
+ - **Библиотека.** `devcontour-harness/report` (`valueReport`,
271
+ `reportMarkdown`, `reportHtml`; без `node:*`), в корне — те же функции,
272
+ `collectReportInput(store)` и `Harness.report()`.
273
+ - **Чтение без файлов.** `report` читает состояние однократно: база без
274
+ журнала открывается неизменяемой и в каталоге состояния не появляется
275
+ служебных `-wal`/`-shm`; если писатель начал работу во время чтения,
276
+ оно повторяется обычным открытием. Прочие читающие команды не менялись.
277
+ - **Схема.** `value-report` (`schemas/value-report.schema.json`,
278
+ `reportVersion: 1`) и данные `report` в `cliDataSchemas`.
279
+
280
+ Определения, правила малых выборок и приватности — [ValueReport](contracts.md#valuereport).
281
+ Отчёт строится из истории как она записана: попытки прежних версий без класса
282
+ отказа показаны `unclassified`, без `wait` — с запасным началом срока, без
283
+ учёта вызовов — с неизвестным расходом; история не переписывается.
284
+
285
+ **Откат.** Ниже этой версии команды `report` нет; состояние она не меняла,
286
+ поэтому откат пакета копии не требует.
287
+
288
+ ### alpha.30: сетевой отказ установки зависимостей
289
+
290
+ Форматы состояния и политики прежние; нового поля в состоянии нет. В
291
+ описании reviewer probe (`probe.json`) — необязательное поле `trustedBase`.
292
+ Установка зависимостей, упавшая на сети или реестре пакетов, теперь отказ
293
+ `environment`, а не `gate`; сообщение начинается с `dependency-network:`.
294
+ Условия:
295
+
296
+ - argv gate попытки или шага `prepare` сам вызывает `npm install|ci`, `pnpm
297
+ install|fetch` или `yarn install`;
298
+ - входы менеджера в дереве (`.npmrc`, `.yarnrc*`, pnpmfile, lockfiles, поля
299
+ зависимостей и скрипты установки `package.json`) совпадают с базой попытки;
300
+ - база не исполняет кода при установке;
301
+ - менеджер вышел сам с кодом 1–127;
302
+ - его отчёт называет только сетевые коды: HTTP 403/407/408/429/5xx реестра,
303
+ обрыв соединения, DNS, TLS.
304
+
305
+ Такой отказ не тратит попытку поручения и ставит паузу очереди `runtime`, как
306
+ любой отказ окружения. Повтор берёт того же кандидата, работу ограничивает
307
+ `MAX_NEUTRAL_FAILURES`. Отказ после правки кандидатом реестра, зависимостей
308
+ или скриптов установки, ошибки lockfile, 404, peer-зависимости и упавший скрипт
309
+ остаются `gate`. Прежде такой отказ gate давал класс `gate`, а шаг `prepare` —
310
+ `unknown`. Хосту, который считает «дефекты, найденные проверками» по
311
+ `failureKind`, новых действий не нужно: эти отказы уходят из счёта сами.
312
+ Правило — [архитектура](architecture.md#что-гарантируется). При откате
313
+ возвращается прежняя классификация; уже записанные попытки сохраняют свой
314
+ класс.
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
+
223
360
  ## Перед обновлением
224
361
 
225
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);
@@ -75,6 +75,7 @@ export declare const probeSpec: z.ZodObject<{
75
75
  }, z.core.$strict>>>;
76
76
  phase: z.ZodOptional<z.ZodString>;
77
77
  sha: z.ZodOptional<z.ZodString>;
78
+ trustedBase: z.ZodOptional<z.ZodString>;
78
79
  scope: z.ZodOptional<z.ZodObject<{
79
80
  attempt: z.ZodString;
80
81
  phase: z.ZodString;
@@ -8,6 +8,7 @@ import { createInterface } from 'node:readline';
8
8
  import { fileURLToPath } from 'node:url';
9
9
  import { z } from 'zod';
10
10
  import { idSchema, relativePathSchema, sha256, TaskFailure, } from "../contracts/index.js";
11
+ import { dependencyNetworkFailure, dependencyNetworkMessage, } from "../environment/dependency-network.js";
11
12
  import { osToolEnv } from "../environment/os-tools.js";
12
13
  import { redactor } from "../environment/redaction.js";
13
14
  import { completedCheck, freshnessEnv, propertyReportEnv, junitSummary, runCheck, sandboxBlockedHosts, } from "../verification/gates.js";
@@ -75,6 +76,8 @@ export const probeSpec = z.object({
75
76
  /** Фаза и SHA ревью: записываются в каждый запуск gate. */
76
77
  phase: z.string().optional(),
77
78
  sha: z.string().optional(),
79
+ /** SHA базы попытки: только с ним gate установки может стать `dependency-network`. */
80
+ trustedBase: z.string().optional(),
78
81
  /**
79
82
  * Вызов reviewer, которому принадлежит журнал: попытка harness, фаза, SHA
80
83
  * и номер вызова. Записывается в каждый исход — по нему итог ревью не
@@ -565,6 +568,15 @@ export class ReviewProbes {
565
568
  const blocked = this.spec.isolation.mode === 'os' && r.code !== 0
566
569
  ? sandboxBlockedHosts(output, this.spec.isolation.domains)
567
570
  : [];
571
+ const network = r.code !== 0 && !r.timedOut && !signal.aborted
572
+ ? await dependencyNetworkFailure({
573
+ argv: gate.command,
574
+ code: r.code,
575
+ output,
576
+ root,
577
+ ...(this.spec.trustedBase ? { base: this.spec.trustedBase } : {}),
578
+ })
579
+ : undefined;
568
580
  if (signal.aborted)
569
581
  outcome = {
570
582
  ...base,
@@ -595,6 +607,14 @@ export class ReviewProbes {
595
607
  failure: 'environment',
596
608
  note: `Песочница закрыла сеть к ${blocked.join(', ')} (нет в isolation.domains): ошибка среды, не находка в коде.`,
597
609
  };
610
+ else if (network)
611
+ outcome = {
612
+ ...base,
613
+ ...streams,
614
+ status: 'error',
615
+ failure: 'environment',
616
+ note: dependencyNetworkMessage(redact(network), 'Это ошибка среды, а не находка в коде.'),
617
+ };
598
618
  else if (r.code !== 0 && report?.status !== 'fresh' && writeDenied.test(output))
599
619
  // Отчёта нет, а проверка получила отказ записи: она писала мимо
600
620
  // HARNESS_REPORT_PATH — в дерево, которое здесь только для чтения.
package/lib/cli.js CHANGED
@@ -21,6 +21,11 @@ import { isSharedOperation, sharedOperations } from "./catalog/shared.js";
21
21
  import { harnessCapabilities } from "./catalog/harness.js";
22
22
  import { hostGitArgs } from "./environment/process.js";
23
23
  import { FileContextSource, FileResultSink, FileWorkSource } from "./connectors/files.js";
24
+ import { SqliteExecutionStore } from "./storage/sqlite.js";
25
+ import { collectReportInput } from "./control/report.js";
26
+ import { writeReportFile } from "./control/report-file.js";
27
+ import { valueReport, reportHtml, reportMarkdown } from "./report/index.js";
28
+ import { handoffMarkdown, handoffPack } from "./handoff/index.js";
24
29
  const usage = `harness ${HARNESS_VERSION}
25
30
 
26
31
  Использование: harness <команда> [параметры]
@@ -211,6 +216,13 @@ const options = {
211
216
  contracts: { type: 'string' },
212
217
  requirements: { type: 'string', multiple: true },
213
218
  'dry-run': { type: 'boolean' },
219
+ detail: { type: 'boolean' },
220
+ since: { type: 'string' },
221
+ until: { type: 'string' },
222
+ 'as-of': { type: 'string' },
223
+ format: { type: 'string' },
224
+ 'no-titles': { type: 'boolean' },
225
+ intent: { type: 'string', multiple: true },
214
226
  };
215
227
  /** Новые флаги H1 допустимы только у своих команд; прежние команды их не принимают. */
216
228
  const flagOwners = {
@@ -223,6 +235,13 @@ const flagOwners = {
223
235
  contracts: ['plan-request', 'plan-check'],
224
236
  requirements: ['plan-request'],
225
237
  'dry-run': ['worktree-cleanup'],
238
+ detail: ['status'],
239
+ since: ['report'],
240
+ until: ['report'],
241
+ 'as-of': ['report'],
242
+ format: ['report', 'handoff'],
243
+ 'no-titles': ['report'],
244
+ intent: ['handoff'],
226
245
  };
227
246
  /** Явное человеческое представление успешного ответа (`--human`). */
228
247
  const presenters = {
@@ -272,6 +291,7 @@ const readText = (path, what) => {
272
291
  throw new HarnessError('INVALID_INPUT', `${what}: не прочитан ${path}: ${error.message}`);
273
292
  }
274
293
  };
294
+ const reportFormats = ['json', 'md', 'html'];
275
295
  async function run(argv) {
276
296
  const [name, ...rest] = argv;
277
297
  if (name === '--version' || name === 'version') {
@@ -430,7 +450,7 @@ async function run(argv) {
430
450
  const h = open(need('state'), binding(need('state')), 'state');
431
451
  try {
432
452
  if (command === 'status')
433
- return { command, data: h.status(v.graph) };
453
+ return { command, data: h.status(v.graph, { detail: Boolean(v.detail) }) };
434
454
  if (command === 'events')
435
455
  return { command, data: h.events(Number(v.after ?? 0), Number(v.limit ?? 100)) };
436
456
  return { command, data: h.result(need('work')) };
@@ -576,6 +596,61 @@ async function run(argv) {
576
596
  }),
577
597
  };
578
598
  }
599
+ case 'report': {
600
+ const state = need('state');
601
+ const format = (v.format ?? 'json');
602
+ if (!reportFormats.includes(format))
603
+ throw new HarnessError('INVALID_INPUT', '--format: ожидается json, md или html', [
604
+ { path: ['--format'], message: String(v.format) },
605
+ ]);
606
+ const file = join(resolve(state), 'state.sqlite');
607
+ if (!existsSync(file))
608
+ throw new HarnessError('NOT_FOUND', 'Каталог состояния не найден: ' + state);
609
+ // Однократное чтение без записи и без файлов в каталоге состояния
610
+ // (неизменяемое открытие с проверкой после чтения, `readOnce`).
611
+ const report = SqliteExecutionStore.readOnce(file, 'devcontour-harness@' + HARNESS_VERSION, (store) => valueReport(collectReportInput(store), {
612
+ ...optional('since', v.since),
613
+ ...optional('until', v.until),
614
+ ...optional('asOf', v['as-of']),
615
+ ...(v['no-titles'] ? { noTitles: true } : {}),
616
+ label: basename(resolve(state)),
617
+ stateDir: resolve(state),
618
+ harnessVersion: HARNESS_VERSION,
619
+ }));
620
+ if (format === 'json' && !v.out)
621
+ return { command, data: report };
622
+ const text = format === 'json'
623
+ ? JSON.stringify(report, null, 2) + '\n'
624
+ : format === 'md'
625
+ ? reportMarkdown(report)
626
+ : reportHtml(report);
627
+ if (!v.out)
628
+ return { command, data: report, text };
629
+ writeReportFile(v.out, state, text);
630
+ return {
631
+ command,
632
+ data: { out: v.out, format, bytes: Buffer.byteLength(text), asOf: report.window.asOf },
633
+ };
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
+ }
579
654
  case 'plan-request': {
580
655
  const b = loadPolicy(need('policy'));
581
656
  const first = b.policy.repositories[0]?.id ?? 'main';
@@ -658,6 +733,9 @@ try {
658
733
  const present = result.command !== 'version' ? presenters[result.command] : undefined;
659
734
  if (present && argv.includes('--human'))
660
735
  text = present(envelope.data);
736
+ // report --format md|html: проверенные данные печатаются текстом, без конверта.
737
+ if (result.text !== undefined)
738
+ text = result.text;
661
739
  }
662
740
  catch (error) {
663
741
  const known = error instanceof HarnessError