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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +22 -3
  2. package/docs/architecture.md +12 -0
  3. package/docs/compatibility.md +21 -18
  4. package/docs/contracts.md +135 -13
  5. package/docs/release-notes/0.1.0-alpha.32.md +33 -0
  6. package/docs/release-notes/0.1.0-alpha.33.md +29 -0
  7. package/docs/release-notes/0.1.0-alpha.34.md +32 -0
  8. package/docs/upgrade.md +137 -0
  9. package/lib/cli.js +2 -2
  10. package/lib/contracts/cli.d.ts +295 -5
  11. package/lib/contracts/events.d.ts +350 -4
  12. package/lib/contracts/events.js +63 -2
  13. package/lib/contracts/failure.d.ts +6 -1
  14. package/lib/contracts/failure.js +5 -1
  15. package/lib/contracts/handoff.d.ts +8 -0
  16. package/lib/contracts/handoff.js +17 -3
  17. package/lib/contracts/published.d.ts +177 -3
  18. package/lib/contracts/report.d.ts +116 -2
  19. package/lib/contracts/report.js +61 -3
  20. package/lib/control/base-move.d.ts +7 -2
  21. package/lib/control/base-move.js +14 -1
  22. package/lib/control/harness.d.ts +44 -8
  23. package/lib/control/harness.js +8 -96
  24. package/lib/control/status.d.ts +235 -0
  25. package/lib/control/status.js +101 -0
  26. package/lib/engine/budget.d.ts +78 -0
  27. package/lib/engine/budget.js +13 -2
  28. package/lib/engine/classify.d.ts +14 -1
  29. package/lib/engine/classify.js +34 -0
  30. package/lib/engine/engine.d.ts +17 -5
  31. package/lib/engine/engine.js +75 -5
  32. package/lib/engine/runner.js +4 -5
  33. package/lib/environment/isolation.d.ts +67 -3
  34. package/lib/environment/isolation.js +148 -5
  35. package/lib/environment/lifecycle.js +1 -1
  36. package/lib/explain/state.d.ts +25 -4
  37. package/lib/explain/state.js +29 -0
  38. package/lib/handoff/index.d.ts +1 -1
  39. package/lib/handoff/markdown.js +4 -2
  40. package/lib/handoff/pack.d.ts +38 -8
  41. package/lib/handoff/pack.js +57 -18
  42. package/lib/index.d.ts +18 -3
  43. package/lib/index.js +18 -2
  44. package/lib/integrations/connector/testing.js +1 -1
  45. package/lib/projections/next.d.ts +3 -1
  46. package/lib/projections/next.js +4 -1
  47. package/lib/projections/stop.d.ts +11 -0
  48. package/lib/projections/stop.js +44 -15
  49. package/lib/report/compute.js +228 -21
  50. package/lib/report/document.js +31 -7
  51. package/lib/verification/gates.js +20 -4
  52. package/package.json +1 -1
  53. package/schemas/handoff-pack.schema.json +6 -0
  54. package/schemas/run-event.schema.json +319 -0
  55. package/schemas/value-report.schema.json +235 -3
@@ -1,4 +1,4 @@
1
- import { activeStatuses } from "./enums.js";
1
+ import { activeStatuses, } from "./enums.js";
2
2
  export const nextSteps = [
3
3
  'accepted',
4
4
  'cancelled',
@@ -67,6 +67,9 @@ export function nextAction(input) {
67
67
  return view('lead', 'review-plan', 'plan-review');
68
68
  if (activeStatuses.includes(input.status))
69
69
  return view('controller', 'wait', 'attempt-running');
70
+ // Упавшая отменой: движок не повторяет, решает человек (повтор или отмена).
71
+ if (input.status === 'failed' && input.failureKind === 'cancelled')
72
+ return view('user', 'user-decision', 'cancelled');
70
73
  if (input.status === 'failed')
71
74
  return input.maxAttempts - input.attempt > 0
72
75
  ? view('controller', 'retry', 'retry-within-budget')
@@ -60,6 +60,17 @@ export type StopInput = {
60
60
  waitingOn?: string[];
61
61
  /** Согласование графа устарело для этой политики (режим operator). */
62
62
  approvalStale?: string;
63
+ /**
64
+ * У отменённой работы: незавершённые работы, которые прямо от неё
65
+ * зависят. Пусто — перепланировать нечего (действия нет); не задано —
66
+ * неизвестно, прежнее replan-dependents.
67
+ */
68
+ openDependents?: string[];
69
+ /**
70
+ * Отменённая работа той же группы, из-за которой движок не
71
+ * восстанавливает группу сам (`repairDecision`: любая отмена — stop).
72
+ */
73
+ repairStoppedBy?: string;
63
74
  /**
64
75
  * Активная попытка без движения по обходу controller: что не
65
76
  * двигалось, сколько и что controller сделает (`action` у stalled).
@@ -163,6 +163,45 @@ function retryPlannedOf(input) {
163
163
  work.attempt < maxAttempts &&
164
164
  repair.groupRepairsUsed < repair.groupRepairBudget);
165
165
  }
166
+ /**
167
+ * Отмена — решение ведущего (перепланировать ждущих), только пока от работы
168
+ * прямо зависит незавершённая; без таких — действия нет. Состав не известен
169
+ * (`undefined`) — прежнее replan-dependents.
170
+ */
171
+ function cancelledOutcome(dependents, phase, failed = false) {
172
+ // Упавшая отменой работа открыта, а движок её не повторяет: без ждущих
173
+ // решает человек — повторить или отменить её.
174
+ if (failed && dependents && !dependents.length)
175
+ return {
176
+ code: 'CANCELLED',
177
+ cause: 'cancelled',
178
+ phase,
179
+ actor: 'user',
180
+ action: 'user-decision',
181
+ note: 'Попытка отменена, работа открыта, движок её не повторяет: повторить (harness retry) или отменить работу.',
182
+ };
183
+ if (dependents && !dependents.length)
184
+ return {
185
+ code: 'CANCELLED',
186
+ cause: 'cancelled',
187
+ phase,
188
+ actor: null,
189
+ action: 'none',
190
+ note: 'Незавершённых зависимых работ нет: перепланировать нечего.',
191
+ };
192
+ return {
193
+ code: 'CANCELLED',
194
+ cause: 'cancelled',
195
+ phase,
196
+ actor: 'lead',
197
+ action: 'replan-dependents',
198
+ ...(dependents
199
+ ? {
200
+ note: `Ждут отменённую: ${dependents.slice(0, 5).join(', ')}${dependents.length > 5 ? ` и ещё ${dependents.length - 5}` : ''}.`,
201
+ }
202
+ : {}),
203
+ };
204
+ }
166
205
  function workOutcome(input, retry) {
167
206
  const { work, control, maxAttempts } = input;
168
207
  const kind = work.failureKind ?? 'unknown';
@@ -327,13 +366,7 @@ function workOutcome(input, retry) {
327
366
  };
328
367
  case 'cancelled':
329
368
  // Поручение со статусом failed и классом cancelled: отмена не повторяется.
330
- return {
331
- code: stopCodeOf(kind),
332
- cause: kind,
333
- phase,
334
- actor: 'lead',
335
- action: 'replan-dependents',
336
- };
369
+ return cancelledOutcome(work.openDependents, phase, true);
337
370
  default:
338
371
  return {
339
372
  code: stopCodeOf(kind),
@@ -354,13 +387,7 @@ function workOutcome(input, retry) {
354
387
  note: `Ждёт ${work.waitingOn.join(', ')}: на них движок остановится; следующий шаг — по их диагнозу.`,
355
388
  };
356
389
  if (work.status === 'cancelled')
357
- return {
358
- code: 'CANCELLED',
359
- cause: 'cancelled',
360
- phase: 'claim',
361
- actor: 'lead',
362
- action: 'replan-dependents',
363
- };
390
+ return cancelledOutcome(work.openDependents, 'claim');
364
391
  if (work.status === 'draft')
365
392
  return {
366
393
  code: 'APPROVAL_REQUIRED',
@@ -575,7 +602,9 @@ export function explainStop(input) {
575
602
  return {
576
603
  ...outcome,
577
604
  retryPlanned: outcome.action === 'retry',
578
- message: message(outcome.cause, note, input.work.failure ? `Отказ: ${input.work.failure}` : undefined),
605
+ message: message(outcome.cause, note, input.work.repairStoppedBy && outcome.action !== 'retry'
606
+ ? `Автоматическое восстановление группы остановлено отменой ${input.work.repairStoppedBy}.`
607
+ : undefined, input.work.failure ? `Отказ: ${input.work.failure}` : undefined),
579
608
  evidence: (input.evidence ?? []).slice(-20).map((e) => ({ ...e })),
580
609
  workId: input.work.id,
581
610
  ...(input.runId ? { runId: input.runId } : {}),
@@ -136,8 +136,18 @@ export function failureBucketOf(a) {
136
136
  return 'operator';
137
137
  return 'unclassified';
138
138
  }
139
- /** Засчитанная попытка: не отказ окружения и не прерывание штатной остановкой. */
140
- const counted = (a) => a.status !== 'active' && a.interrupted !== 'shutdown' && failureBucketOf(a) !== 'environment';
139
+ /**
140
+ * Засчитанная в предел попыток — то же правило, что у движка (`counted` в
141
+ * `attempt.diagnosed`): не засчитаны прерванные штатной остановкой, отказы до
142
+ * работы (`blocked`), отказы окружения и провайдера (`environment`,
143
+ * `provider-auth`) и истёкшее владение. Зависание (`stalled`) засчитано.
144
+ */
145
+ const counted = (a) => a.status !== 'active' &&
146
+ a.interrupted !== 'shutdown' &&
147
+ !a.blocked &&
148
+ a.status !== 'expired' &&
149
+ a.failureKind !== 'environment' &&
150
+ a.failureKind !== 'provider-auth';
141
151
  /** Gate подготовки: установка зависимостей — его отказ часто сетевой (M6). */
142
152
  const setupGate = (gate) => /install|setup|bootstrap|deps|dependenc/i.test(gate);
143
153
  /** Отказ gate только в gates подготовки: возможно, сеть или реестр, а не код (M6). */
@@ -486,14 +496,147 @@ export function valueReport(input, options = {}) {
486
496
  const operatorDecisions = [...episodes.values()].filter((r) => r.decision?.source.kind === 'operator' && inWindow(w, r.decision.decidedAt));
487
497
  const holds = windowEvents.filter((e) => e.type === 'work.held' && !e.payload.released);
488
498
  const cancelledAttempts = windowAttempts.filter((a) => failureBucketOf(a) === 'operator');
489
- // Действие человека — только запись с актёром-человеком (решение recovery
490
- // оператора). Удержание (`work.held`) и отмена попытки актёра не называют:
491
- // их ставят и операции хоста (например, смена контракта), поэтому они
492
- // показаны отдельно и в действия человека не входят.
499
+ // Действие человека — только запись с актёром-человеком: решение recovery
500
+ // оператора, повтор и отмена с `by: operator`. Удержание (`work.held`) актёра
501
+ // не называет: его ставят и операции хоста (например, смена контракта),
502
+ // поэтому оно показано отдельно и в действия человека не входит.
493
503
  const actedOn = new Set([...episodes.values()]
494
504
  .filter((r) => r.decision?.source.kind === 'operator')
495
505
  .map((r) => r.workId));
506
+ // Вмешательства с актёром (`work.retried`, `work.cancelled`, `base.moved`):
507
+ // запись идёт с первого события версии, которая их пишет (она же пишет
508
+ // `attempt.diagnosed` при каждом отказе). Раньше него действие могло быть,
509
+ // но не записано, — поручение, начатое раньше, «без действий» не считается.
510
+ const interventionTypes = new Set([
511
+ 'work.retried',
512
+ 'work.cancelled',
513
+ 'base.moved',
514
+ 'attempt.diagnosed',
515
+ ]);
516
+ const firstRecorded = events.find((e) => interventionTypes.has(e.type));
517
+ const recordedFrom = firstRecorded ? at(firstRecorded.at) : undefined;
518
+ // Актёр не назван: повтор или отмена хостом (`host`) и любое удержание
519
+ // (`work.held`, его ставит и человек, и операция хоста) — поручение с ними
520
+ // «без действий человека» не считается, а неизвестно.
521
+ const unattributed = new Set();
522
+ // Порядок — по `seq` журнала, а не по времени: `at` события — часы записи,
523
+ // а время попытки — часы движка (их задаёт хост), сравнивать их нельзя.
524
+ const reopenedAt = new Map();
525
+ const registeredAt = new Map();
526
+ const endSeq = new Map();
527
+ const startSeq = new Map();
528
+ const push = (m, key, ms) => m.set(key, [...(m.get(key) ?? []), ms]);
529
+ for (const e of events) {
530
+ if (e.type === 'graph.registered' && e.graphId)
531
+ push(registeredAt, e.graphId, e.seq);
532
+ if (e.runId && e.type === 'attempt.claimed')
533
+ startSeq.set(e.runId, e.seq);
534
+ if (e.runId &&
535
+ (e.type === 'attempt.failed' ||
536
+ e.type === 'attempt.cancelled' ||
537
+ e.type === 'attempt.expired' ||
538
+ // Записывающая версия пишет их сразу за концом попытки: конец — с ними.
539
+ e.type === 'attempt.diagnosed' ||
540
+ e.type === 'work.cancelled'))
541
+ endSeq.set(e.runId, Math.max(endSeq.get(e.runId) ?? 0, e.seq));
542
+ if (!e.workId)
543
+ continue;
544
+ if (e.type === 'work.held')
545
+ unattributed.add(e.workId);
546
+ if (e.type === 'work.retried')
547
+ push(reopenedAt, e.workId, e.seq);
548
+ if (e.type !== 'work.retried' && e.type !== 'work.cancelled')
549
+ continue;
550
+ if (e.payload.by === 'operator')
551
+ actedOn.add(e.workId);
552
+ else if (e.payload.by === 'host')
553
+ unattributed.add(e.workId);
554
+ }
555
+ // Пробел записи (откат на версию без этих событий и повторное обновление):
556
+ // после начала записи новая попытка поручения после отказа или отмены
557
+ // невозможна без повтора — нет ни `work.retried`, ни новой редакции графа
558
+ // между концом прежней попытки и выдачей новой (по `seq`), значит, повтор
559
+ // шёл версией, которая его не записывает. Без этих событий попытки (журнал
560
+ // неполон) пробел не определяется.
561
+ const gapWorks = new Set();
562
+ const gapInWindow = new Set();
563
+ if (recordedFrom !== undefined)
564
+ for (const f of facts)
565
+ for (let i = 1; i < f.attempts.length; i++) {
566
+ const prev = f.attempts[i - 1];
567
+ const cur = f.attempts[i];
568
+ if (!finishedStatuses.has(prev.status) || prev.interrupted === 'shutdown')
569
+ continue;
570
+ const from = endSeq.get(prev.id);
571
+ const to = startSeq.get(cur.id);
572
+ if (from === undefined || to === undefined || from < firstRecorded.seq)
573
+ continue;
574
+ const between = (seq) => seq > from && seq < to;
575
+ if ((reopenedAt.get(f.work.id) ?? []).some(between) ||
576
+ (registeredAt.get(f.work.graphId) ?? []).some(between))
577
+ continue;
578
+ gapWorks.add(f.work.id);
579
+ if (inWindow(w, cur.startedAt))
580
+ gapInWindow.add(f.work.id);
581
+ }
582
+ /** Начало жизни поручения: согласование первой попытки или поручения, иначе первая попытка. */
583
+ const startOf = (f) => {
584
+ const first = f.attempts[0];
585
+ const iso = first?.wait?.approvedAt ?? f.work.approvedAt ?? first?.startedAt;
586
+ return iso ? at(iso) : undefined;
587
+ };
588
+ const coveredWork = (f) => {
589
+ const start = startOf(f);
590
+ return (recordedFrom !== undefined &&
591
+ start !== undefined &&
592
+ start >= recordedFrom &&
593
+ !gapWorks.has(f.work.id));
594
+ };
496
595
  const acceptedActed = accepted.filter((f) => actedOn.has(f.work.id)).length;
596
+ // Отсутствие действия человека известно, если поручение начато после
597
+ // начала записи, без пробела в ней, и у него нет действий без актёра.
598
+ const acceptedUnknown = accepted.filter((f) => !actedOn.has(f.work.id) && (!coveredWork(f) || unattributed.has(f.work.id))).length;
599
+ const zero = (actors) => Object.fromEntries(actors.map((a) => [a, 0]));
600
+ const recorded = recordedFrom === undefined
601
+ ? null
602
+ : (() => {
603
+ const r = {
604
+ from: toIso(recordedFrom),
605
+ bound: 'exact',
606
+ retries: zero(['operator', 'recovery', 'host']),
607
+ resets: zero(['operator', 'recovery', 'host']),
608
+ cancellations: zero(['operator', 'host', 'graph']),
609
+ cancelledWithoutAttempt: 0,
610
+ baseMoves: zero(['operator', 'controller', 'host']),
611
+ baseMovesBound: 'lower',
612
+ gaps: gapInWindow.size,
613
+ };
614
+ for (const e of windowEvents)
615
+ if (e.type === 'work.retried') {
616
+ r.retries[e.payload.by] += 1;
617
+ if (e.payload.reset)
618
+ r.resets[e.payload.by] += 1;
619
+ }
620
+ else if (e.type === 'work.cancelled') {
621
+ r.cancellations[e.payload.by] += 1;
622
+ if (!e.payload.hadAttempt)
623
+ r.cancelledWithoutAttempt += 1;
624
+ }
625
+ else if (e.type === 'base.moved')
626
+ r.baseMoves[e.payload.by] += 1;
627
+ // Окно начинается раньше записи: в нём есть попытки или события до неё.
628
+ const before = (ms) => ms < recordedFrom;
629
+ if (gapInWindow.size > 0 ||
630
+ windowAttempts.some((a) => before(at(a.startedAt))) ||
631
+ windowEvents.some((e) => before(at(e.at))) ||
632
+ accepted.some((f) => before(startOf(f) ?? -Infinity)))
633
+ r.bound = 'lower';
634
+ return r;
635
+ })();
636
+ // Сумма — только точная: при нижней границе её нет (`null`), числа по
637
+ // актёрам с границей — в `recorded`. Сдвиги базы — всегда нижняя граница:
638
+ // перенос вне `fencedRefMove` (например, `moveBase` без `move`) не пишется.
639
+ const total = (counts) => counts && recorded?.bound === 'exact' ? sum(Object.values(counts)) : null;
497
640
  const escalated = new Set([
498
641
  ...[...episodes.values()]
499
642
  .filter((r) => (r.status === 'awaiting-user' || r.status === 'stopped') && inWindow(w, r.openedAt))
@@ -730,6 +873,38 @@ export function valueReport(input, options = {}) {
730
873
  const envAttempts = failedAttempts.filter((a) => failureBucketOf(a) === 'environment');
731
874
  const envCount = envAttempts.length;
732
875
  const setupCheckFailures = failedAttempts.filter(setupOnlyFailure).length;
876
+ // Подпричины окружения (E3): `attempt.diagnosed` той же попытки; отказ
877
+ // без события записан до версии, которая их пишет.
878
+ const diagnosisOf = new Map();
879
+ for (const e of events)
880
+ if (e.type === 'attempt.diagnosed' && e.runId)
881
+ diagnosisOf.set(e.runId, e.payload);
882
+ const causes = diagnosisOf.size
883
+ ? (() => {
884
+ const rows = new Map();
885
+ let undiagnosed = 0;
886
+ for (const a of envAttempts) {
887
+ const d = diagnosisOf.get(a.id);
888
+ if (!d) {
889
+ undiagnosed += 1;
890
+ continue;
891
+ }
892
+ const row = rows.get(d.cause) ?? { count: 0, counted: 0 };
893
+ row.count += 1;
894
+ if (d.counted)
895
+ row.counted += 1;
896
+ rows.set(d.cause, row);
897
+ }
898
+ return {
899
+ rows: [...rows.entries()]
900
+ .map(([cause, r]) => ({ cause, count: r.count, counted: r.counted }))
901
+ .sort((x, y) => y.count - x.count || cmp(x.cause, y.cause)),
902
+ diagnosed: envAttempts.length - undiagnosed,
903
+ undiagnosed,
904
+ bound: undiagnosed ? 'lower' : 'exact',
905
+ };
906
+ })()
907
+ : null;
733
908
  const rechecks = { flaky: 0, confirmed: 0 };
734
909
  for (const { e } of windowEvidence)
735
910
  if (e.recheck)
@@ -845,17 +1020,21 @@ export function valueReport(input, options = {}) {
845
1020
  itemsTruncated: allItems.length > items.length,
846
1021
  },
847
1022
  autonomy: {
848
- withAction: measure(acceptedActed, accepted.length, 0, accepted.length ? 'lower' : 'unknown'),
1023
+ withAction: measure(acceptedActed, accepted.length, recorded ? acceptedUnknown : 0, !accepted.length ? 'unknown' : !recorded || acceptedUnknown ? 'lower' : 'exact'),
849
1024
  // Без записанного актёра повторов, сбросов и сдвигов базы «без действий
850
1025
  // человека» не измерить: значение неизвестно, а не верхняя граница N.
851
- withoutAction: measure(null, accepted.length, accepted.length, 'unknown'),
1026
+ // С записью — нижняя граница, пока есть поручения, начатые до неё.
1027
+ withoutAction: recorded
1028
+ ? measure(accepted.length - acceptedActed - acceptedUnknown, accepted.length, acceptedUnknown, !accepted.length ? 'unknown' : acceptedUnknown ? 'lower' : 'exact')
1029
+ : measure(null, accepted.length, accepted.length, 'unknown'),
852
1030
  actions: {
853
1031
  operatorDecisions: operatorDecisions.length,
854
1032
  holds: holds.length,
855
1033
  cancelledAttempts: cancelledAttempts.length,
856
- retries: null,
857
- resets: null,
1034
+ retries: total(recorded?.retries),
1035
+ resets: total(recorded?.resets),
858
1036
  baseMoves: null,
1037
+ recorded,
859
1038
  },
860
1039
  approvals,
861
1040
  pauses,
@@ -930,7 +1109,7 @@ export function valueReport(input, options = {}) {
930
1109
  share: measure(envCount, classified, unclassifiedOrUnknown, !classified ? 'unknown' : setupCheckFailures ? 'lower' : 'exact'),
931
1110
  setupCheckFailures,
932
1111
  timeLimit: bucketCounts.get('time-limit') ?? 0,
933
- causes: null,
1112
+ causes,
934
1113
  neutral: {
935
1114
  // Тот же расход, что у корзины `environment` раздела расходов.
936
1115
  costBound: attemptsBound(attemptCosts.filter(({ a }) => envAttempts.includes(a))),
@@ -1123,7 +1302,7 @@ function summaryOf(r, failedAttempts) {
1123
1302
  text: fp.bound === 'lower'
1124
1303
  ? `${plural(n, 'task')} accepted. At least ${fp.value} of them${pct(fp.value ?? 0, n)} on the first try; for ${plural(fp.unknown, 'more task')} it is unknown (failures without a class).`
1125
1304
  : `${plural(n, 'task')} accepted. ${fp.value} of them${pct(fp.value ?? 0, n)} on the first try.`,
1126
- basis: `Accepted: merged after all required checks and an independent review. First try: the accepting attempt was the only counted attempt (environment failures and shutdowns are not counted). Window: ${window}.`,
1305
+ basis: `Accepted: merged after all required checks and an independent review. First try: the accepting attempt was the only counted attempt (environment failures except stalls, blocked-before-work attempts, expired leases and shutdowns are not counted). Window: ${window}.`,
1127
1306
  measure: fp,
1128
1307
  },
1129
1308
  {
@@ -1168,23 +1347,33 @@ function summaryOf(r, failedAttempts) {
1168
1347
  };
1169
1348
  }
1170
1349
  function limitationsOf(r) {
1350
+ const recorded = r.autonomy.actions.recorded;
1351
+ const causes = r.environment.causes;
1171
1352
  const out = [
1172
1353
  {
1173
1354
  id: 'no-baseline',
1174
1355
  text: 'There is no before-harness baseline: the report does not compare with work done without the harness.',
1175
1356
  },
1176
- {
1177
- id: 'actions-not-recorded',
1178
- text: 'Human actions are counted only where a person is recorded as the actor (operator recovery decisions); retries, resets, cancellations and base moves have no recorded actor yet, so tasks that needed no human action are not measurable yet.',
1179
- },
1357
+ ...(recorded === null
1358
+ ? [
1359
+ {
1360
+ id: 'actions-not-recorded',
1361
+ text: 'Human actions are counted only where a person is recorded as the actor (operator recovery decisions); retries, resets, cancellations and base moves have no recorded actor yet, so tasks that needed no human action are not measurable yet.',
1362
+ },
1363
+ ]
1364
+ : []),
1180
1365
  {
1181
1366
  id: 'check-network',
1182
1367
  text: 'Network or registry errors inside checks are classified as check failures, so rejections by checks can be overstated; setup checks are marked.',
1183
1368
  },
1184
- {
1185
- id: 'environment-cause',
1186
- text: 'Environment failures have no recorded sub-cause (sandbox, network, provider, lease).',
1187
- },
1369
+ ...(causes === null
1370
+ ? [
1371
+ {
1372
+ id: 'environment-cause',
1373
+ text: 'Environment failures have no recorded sub-cause (sandbox, network, provider, lease).',
1374
+ },
1375
+ ]
1376
+ : []),
1188
1377
  {
1189
1378
  id: 'reviewer-precision',
1190
1379
  text: 'A rejected candidate is not proof of a real defect: reviewer precision is not measured; withdrawn findings are only a proxy.',
@@ -1199,13 +1388,31 @@ function limitationsOf(r) {
1199
1388
  if (cond)
1200
1389
  out.push({ id, text });
1201
1390
  };
1391
+ if (recorded) {
1392
+ const unknown = r.autonomy.withoutAction.unknown;
1393
+ add('actions-from', recorded.bound === 'lower', `Retries, resets, cancellations and base moves are recorded with their actor from ${recorded.from}; the window has activity before that, so action counts are lower bounds.`);
1394
+ add('actions-unknown', unknown > 0, `${plural(unknown, 'accepted task')} started before actions were recorded, ${unknown === 1 ? 'was' : 'were'} held, or ${unknown === 1 ? 'was' : 'were'} retried or cancelled by the host without a named actor, so tasks that needed no human action are a lower bound.`);
1395
+ add('recording-gap', recorded.gaps > 0, `${plural(recorded.gaps, 'task')} got a new attempt after a failure or cancellation without a recorded retry (an older version ran in between, for example after a rollback); actions there are not recorded.`);
1396
+ out.push({
1397
+ id: 'base-moves',
1398
+ text: 'Base moves are a lower bound: moves outside the fenced path are not recorded; they are not attributed to tasks.',
1399
+ });
1400
+ out.push({
1401
+ id: 'rollback-gap',
1402
+ text: 'If an older version ran after recording began (rollback and re-upgrade), its retries, cancellations and base moves are not recorded; only gaps that left a new attempt without a retry are detected.',
1403
+ });
1404
+ }
1405
+ if (causes)
1406
+ add('environment-cause-from', causes.undiagnosed > 0, `${plural(causes.undiagnosed, 'environment failure')} recorded before sub-causes were recorded ${causes.undiagnosed === 1 ? 'has' : 'have'} no sub-cause; sub-causes are shown for the rest.`);
1202
1407
  const unclassified = r.environment.buckets.find((b) => b.bucket === 'unclassified').count;
1203
1408
  add('unclassified', unclassified > 0, `${plural(unclassified, 'failed attempt')} without a failure class (recorded before classification) ${unclassified === 1 ? 'is' : 'are'} shown as unclassified, not as defects.`);
1204
1409
  add('timings', c.attempts > c.withTimings, `${c.attempts - c.withTimings} of ${c.attempts} attempts have no stage timings; stage time covers the rest.`);
1205
1410
  add('calls', r.cost.attemptsWithoutCalls > 0, `${r.cost.attemptsWithoutCalls} of ${c.attempts} attempts have no call records, so their spend is unknown.`);
1206
1411
  add('partial-calls', r.cost.attemptsPartialCalls > 0, `${r.cost.attemptsPartialCalls} of ${c.attempts} attempts have call records that are not marked complete; their spend is a lower bound.`);
1207
1412
  add('done-without-attempt', c.doneWithoutAttempt > 0, `${plural(c.doneWithoutAttempt, 'done task')} without a succeeded attempt ${c.doneWithoutAttempt === 1 ? 'has' : 'have'} no acceptance time and ${c.doneWithoutAttempt === 1 ? 'is' : 'are'} not counted as accepted.`);
1208
- add('holds-actor', r.autonomy.actions.holds + r.autonomy.actions.cancelledAttempts > 0, 'Holds and cancelled attempts record no actor (host operations hold tasks too), so they are not counted as human actions.');
1413
+ add('holds-actor', r.autonomy.actions.holds + (recorded ? 0 : r.autonomy.actions.cancelledAttempts) > 0, recorded
1414
+ ? 'Holds record no actor (host operations hold tasks too): they are not counted as human actions, and held tasks are counted as unknown, not as needing no human action.'
1415
+ : 'Holds and cancelled attempts record no actor (host operations hold tasks too), so they are not counted as human actions.');
1209
1416
  add('approvals-unknown', r.autonomy.approvals.source === 'none', 'No approval records: plan approvals are unknown, not zero.');
1210
1417
  add('prices', r.cost.unknown.total > 0, `${r.cost.unknown.total} of ${r.cost.calls} calls have no known price (no tariff ${r.cost.unknown.noPrice}, incomplete telemetry ${r.cost.unknown.incomplete}, active ${r.cost.unknown.active}, abandoned ${r.cost.unknown.abandoned}); spend is a lower bound.`);
1211
1418
  add('lead-fallback', r.speed.leadTimeFallback > 0, `${plural(r.speed.leadTimeFallback, 'accepted task')} started from the task approval time, which a re-approval overwrites.`);
@@ -29,6 +29,22 @@ const bucketLabels = {
29
29
  unknown: 'unknown',
30
30
  unclassified: 'unclassified (legacy)',
31
31
  };
32
+ const causeLabels = {
33
+ 'sandbox-launch': 'sandbox did not start the command',
34
+ 'sandbox-network': 'sandbox closed the network',
35
+ 'sandbox-filesystem': 'sandbox denied file access',
36
+ 'sandbox-policy': 'sandbox policy could not be built',
37
+ 'dependency-network': 'dependency install network or registry',
38
+ 'provider-auth': 'provider login',
39
+ 'provider-limit': 'provider limit or balance',
40
+ transport: 'network to the provider',
41
+ preflight: 'setup before work',
42
+ 'lease-expired': 'lease expired',
43
+ stalled: 'stalled process',
44
+ shutdown: 'controller shutdown',
45
+ other: 'other',
46
+ none: 'not an environment cause',
47
+ };
32
48
  /** Блоки отчёта в порядке разделов (`docs/contracts.md`, «Отчёт»). */
33
49
  export function reportBlocks(r) {
34
50
  const c = r.coverage;
@@ -85,13 +101,19 @@ export function reportBlocks(r) {
85
101
  p(`Showing ${d.items.length} of ${d.itemsTotal} items.`, true);
86
102
  }
87
103
  h(2, 'Autonomy');
104
+ const rec = a.actions.recorded;
105
+ const ge = rec?.bound === 'lower' ? '≥ ' : '';
88
106
  list([
89
- `Accepted tasks that needed no human action: not measurable yet (retries, resets and base moves have no recorded actor). Accepted tasks with an operator recovery decision: ${a.withAction.value ?? 0} of ${a.withAction.n}.`,
90
- `Human actions with a recorded actor: operator recovery decisions ${a.actions.operatorDecisions}. Without a recorded actor (not counted as human): holds ${a.actions.holds}, cancelled attempts ${a.actions.cancelledAttempts}. ${actionsLine([
91
- ['retries', a.actions.retries],
92
- ['resets', a.actions.resets],
93
- ['base moves', a.actions.baseMoves],
94
- ])}`,
107
+ rec
108
+ ? `Accepted tasks that needed no human action: ${formatMeasureRatio(a.withoutAction)}. With a recorded human action (operator retry, cancellation or recovery decision): ${formatMeasureRatio(a.withAction)}.`
109
+ : `Accepted tasks that needed no human action: not measurable yet (retries, resets and base moves have no recorded actor). Accepted tasks with an operator recovery decision: ${a.withAction.value ?? 0} of ${a.withAction.n}.`,
110
+ rec
111
+ ? `Human actions: operator recovery decisions ${a.actions.operatorDecisions}, operator retries ${ge}${rec.retries.operator} (resets ${ge}${rec.resets.operator}), operator cancellations ${ge}${rec.cancellations.operator}, operator base moves ≥ ${rec.baseMoves.operator}. Automatic: recovery retries ${ge}${rec.retries.recovery}, controller base moves ≥ ${rec.baseMoves.controller}, cancellations by a new graph revision ${ge}${rec.cancellations.graph}. By the host without a named actor: retries ${ge}${rec.retries.host}, cancellations ${ge}${rec.cancellations.host}, base moves ≥ ${rec.baseMoves.host}. Tasks cancelled without an active attempt: ${ge}${rec.cancelledWithoutAttempt}; cancelled attempts ${a.actions.cancelledAttempts}. Without a recorded actor: holds ${a.actions.holds} (held tasks count as unknown). Recorded from ${rec.from}.`
112
+ : `Human actions with a recorded actor: operator recovery decisions ${a.actions.operatorDecisions}. Without a recorded actor (not counted as human): holds ${a.actions.holds}, cancelled attempts ${a.actions.cancelledAttempts}. ${actionsLine([
113
+ ['retries', a.actions.retries],
114
+ ['resets', a.actions.resets],
115
+ ['base moves', a.actions.baseMoves],
116
+ ])}`,
95
117
  a.approvals.source === 'none'
96
118
  ? 'Plan approvals: unknown (no approval records).'
97
119
  : `Plan approvals: operator ${a.approvals.operator}, agent ${a.approvals.agent} (${a.approvals.source === 'events' ? 'from events' : a.approvals.source === 'state' ? 'current approvals of graphs only' : 'from events, and current approvals of graphs without events'}).`,
@@ -157,7 +179,9 @@ export function reportBlocks(r) {
157
179
  list([
158
180
  `Environment failures cost ${formatDuration(e.neutral.machineMs)} of machine time and ${money(e.neutral.costBound, e.neutral.knownUsd)} known spend; blocked before work (not counted as an attempt): ${e.neutral.blocked}; queue stops caused by the environment: ${e.neutral.runtimePauses}.`,
159
181
  `Integration check rechecks: ${e.rechecks.flaky} flaky (false rejection avoided), ${e.rechecks.confirmed} confirmed.`,
160
- 'Environment sub-causes: not recorded yet.',
182
+ e.causes
183
+ ? `Environment sub-causes${e.causes.undiagnosed ? ` (${e.causes.undiagnosed} earlier ${e.causes.undiagnosed === 1 ? 'failure' : 'failures'} without a recorded sub-cause)` : ''}: ${e.causes.rows.length ? e.causes.rows.map((x) => `${causeLabels[x.cause] ?? x.cause} ${x.count}${x.counted ? ` (${x.counted} counted as an attempt)` : ''}`).join(', ') : 'none in the window'}.`
184
+ : 'Environment sub-causes: not recorded yet.',
161
185
  ]);
162
186
  h(2, 'Weekly trend');
163
187
  if (r.weeks.active)
@@ -6,7 +6,7 @@ import { createHash, randomUUID } from 'node:crypto';
6
6
  import { XMLParser, XMLValidator } from 'fast-xml-parser';
7
7
  import { sha256, } from "../contracts/index.js";
8
8
  import { command, git } from "../environment/process.js";
9
- import { isolation, isolatedCommand, isolationSupport, protectedChanges, protectedSnapshot, SandboxPolicyError, sandboxDenials, watchSandboxLog, } from "../environment/isolation.js";
9
+ import { isolation, isolatedCommand, srtTempDir, isolationSupport, protectedChanges, protectedSnapshot, SandboxPolicyError, sandboxDenials, watchSandboxLog, } from "../environment/isolation.js";
10
10
  import { UntrustedCheckoutError } from "../environment/git-trust.js";
11
11
  import { TaskFailure } from "../engine/failure.js";
12
12
  import { redactDeep } from "../environment/redaction.js";
@@ -343,6 +343,8 @@ h, options) {
343
343
  // Метка старта — вне TMPDIR команды: проверка, чистящая свой временный
344
344
  // каталог, не должна стирать признак того, что она уже начиналась.
345
345
  const marks = await realpath(await mkdtemp(join(tmpdir(), 'dc-start-')));
346
+ // Свой короткий временный каталог srt (`srtTempDir`), если его пришлось создать.
347
+ let srtTemp;
346
348
  try {
347
349
  if (h.config.isolation.mode === 'os') {
348
350
  const support = isolationBackend.check();
@@ -365,7 +367,12 @@ h, options) {
365
367
  const workdir = await realpath(options.cwd);
366
368
  const tag = options.violations ? 'dc' + randomUUID().replace(/-/g, '').slice(0, 16) : '';
367
369
  const roots = isolation({ write: options.write, controller: [] }).write.filter((w) => workdir === w || workdir.startsWith(w + sep));
368
- const wrapped = await isolatedCommand(policy, argv, options.settingsDir, scratch, started, workdir, roots.length ? roots : [workdir], process.platform, tag, token);
370
+ // Сокеты srt — во временном каталоге его процесса: при глубоком TMPDIR
371
+ // путь длиннее предела unix-сокета, и srt не стартует.
372
+ const srt = await srtTempDir();
373
+ if (srt.created)
374
+ srtTemp = srt.dir;
375
+ const wrapped = await isolatedCommand(policy, argv, options.settingsDir, scratch, started, workdir, roots.length ? roots : [workdir], process.platform, tag, token, srt.dir);
369
376
  argv = wrapped.argv;
370
377
  env = { ...env, ...wrapped.env };
371
378
  cwd = wrapped.cwd;
@@ -445,6 +452,7 @@ h, options) {
445
452
  const removed = await Promise.allSettled([
446
453
  checkCleanup.remove(scratch),
447
454
  checkCleanup.remove(marks),
455
+ ...(srtTemp ? [checkCleanup.remove(srtTemp)] : []),
448
456
  ]);
449
457
  const failed = removed.find((r) => r.status === 'rejected');
450
458
  if (failed) {
@@ -580,6 +588,8 @@ export async function runGate(run) {
580
588
  // Восстановленный из cache зелёный отчёт иначе выглядел бы свежим.
581
589
  const freshness = freshnessEnv(gate.kind, run.execution.env);
582
590
  let kind = 'gate';
591
+ /** Причина отказа окружения (`attempt.diagnosed`), когда она известна здесь. */
592
+ let cause;
583
593
  // Заголовок лога — фактические каталог и argv запуска: digest лога входит в
584
594
  // evidence, и запись называет, где и чем проверка исполнялась.
585
595
  let passed = false, summary = '', log = `# harness gate ${gate.id}: cwd=${relative(root, gateCwd) || '.'} argv=${JSON.stringify(gate.command.map(redact))}${gate.kind === 'test' ? ` fresh=${redact(JSON.stringify(freshness))}` : ''}\n`, exitCode = -1, manifest;
@@ -644,6 +654,7 @@ export async function runGate(run) {
644
654
  // in PATH» остаётся только причиной. Прочие отказы — провал проверки.
645
655
  if (result.launchFailed) {
646
656
  kind = 'environment';
657
+ cause = 'sandbox-launch';
647
658
  throw new Error(`песочница ОС не запустила команду проверки (попыток: ${result.attempts}): проверка не исполнялась. ` +
648
659
  `Код выхода ${result.code}: ${diagnostic(result.stderr, result.stdout, redact)}`);
649
660
  }
@@ -663,6 +674,7 @@ export async function runGate(run) {
663
674
  : [];
664
675
  if (blocked.length) {
665
676
  kind = 'environment';
677
+ cause = 'sandbox-network';
666
678
  throw new Error(`песочница проверки закрыла сеть к ${blocked.join(', ')}: этих доменов нет в isolation.domains. ` +
667
679
  `Код выхода ${result.code}: ${diagnostic(result.stderr, result.stdout, redact)}`);
668
680
  }
@@ -673,6 +685,7 @@ export async function runGate(run) {
673
685
  : [];
674
686
  if (denied.length) {
675
687
  kind = 'environment';
688
+ cause = 'sandbox-filesystem';
676
689
  throw new Error(`песочница проверки отказала в доступе: ` +
677
690
  denied
678
691
  .slice(0, 3)
@@ -693,6 +706,7 @@ export async function runGate(run) {
693
706
  });
694
707
  if (network) {
695
708
  kind = 'environment';
709
+ cause = 'dependency-network';
696
710
  throw new Error(dependencyNetworkMessage(redact(network), `Код выхода ${result.code}: ${diagnostic(result.stderr, result.stdout, redact)}`));
697
711
  }
698
712
  throw new Error([
@@ -722,8 +736,10 @@ export async function runGate(run) {
722
736
  catch (error) {
723
737
  // Сборка политики не удалась — отказ среды; checkout, который увёл бы
724
738
  // git хоста в чужую конфигурацию, — нарушение области.
725
- if (error instanceof SandboxPolicyError)
739
+ if (error instanceof SandboxPolicyError) {
726
740
  kind = 'environment';
741
+ cause = 'sandbox-policy';
742
+ }
727
743
  if (error instanceof UntrustedCheckoutError)
728
744
  kind = 'scope-violation';
729
745
  const message = error instanceof Error ? error.message : String(error);
@@ -880,7 +896,7 @@ export async function runGate(run) {
880
896
  bound: [...new Set(failing.filter((id) => declared.has(id)))],
881
897
  unbound: [...new Set(failing.filter((id) => !declared.has(id)))],
882
898
  }
883
- : undefined);
899
+ : undefined, kind === 'environment' ? cause : undefined);
884
900
  }
885
901
  return evidence;
886
902
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "devcontour-harness",
3
- "version": "0.1.0-alpha.31",
3
+ "version": "0.1.0-alpha.34",
4
4
  "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -1370,6 +1370,12 @@
1370
1370
  "minimum": 0,
1371
1371
  "maximum": 9007199254740991
1372
1372
  },
1373
+ "budgetsShared": {
1374
+ "default": 0,
1375
+ "type": "integer",
1376
+ "minimum": 0,
1377
+ "maximum": 9007199254740991
1378
+ },
1373
1379
  "repairs": {
1374
1380
  "type": "integer",
1375
1381
  "minimum": 0,