devcontour-harness 0.1.0-alpha.46 → 0.1.0-alpha.47

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 (43) hide show
  1. package/README.md +11 -2
  2. package/docs/compatibility.md +4 -1
  3. package/docs/contracts.md +7 -1
  4. package/docs/release-notes/0.1.0-alpha.47.md +138 -0
  5. package/docs/upgrade.md +62 -0
  6. package/lib/agents/review-probe.js +8 -3
  7. package/lib/contracts/cli.d.ts +10 -0
  8. package/lib/contracts/events.d.ts +13 -1
  9. package/lib/contracts/events.js +2 -0
  10. package/lib/contracts/execution.d.ts +1 -0
  11. package/lib/contracts/execution.js +8 -0
  12. package/lib/contracts/ports.d.ts +54 -0
  13. package/lib/contracts/published.d.ts +7 -0
  14. package/lib/contracts/report.d.ts +4 -0
  15. package/lib/control/harness.d.ts +1 -1
  16. package/lib/engine/classify.d.ts +6 -0
  17. package/lib/engine/classify.js +26 -0
  18. package/lib/engine/engine.d.ts +13 -0
  19. package/lib/engine/engine.js +46 -2
  20. package/lib/engine/runner.d.ts +11 -6
  21. package/lib/engine/runner.js +90 -22
  22. package/lib/environment/host-load.d.ts +12 -0
  23. package/lib/environment/host-load.js +7 -0
  24. package/lib/environment/lifecycle.d.ts +12 -1
  25. package/lib/environment/lifecycle.js +19 -2
  26. package/lib/environment/process.d.ts +71 -1
  27. package/lib/environment/process.js +149 -31
  28. package/lib/index.d.ts +4 -0
  29. package/lib/index.js +6 -0
  30. package/lib/report/document.js +2 -0
  31. package/lib/storage/sqlite.d.ts +47 -4
  32. package/lib/storage/sqlite.js +279 -34
  33. package/lib/testing/store-contract.d.ts +9 -0
  34. package/lib/testing/store-contract.js +235 -0
  35. package/lib/verification/gates-at.js +15 -1
  36. package/lib/verification/gates.d.ts +3 -10
  37. package/lib/verification/gates.js +136 -15
  38. package/lib/verification/reaped.d.ts +24 -0
  39. package/lib/verification/reaped.js +24 -0
  40. package/package.json +1 -1
  41. package/schemas/execution-document.schema.json +4 -0
  42. package/schemas/run-event.schema.json +2 -0
  43. package/schemas/value-report.schema.json +3 -1
@@ -1,5 +1,19 @@
1
1
  import { BlockedError, HarnessError, TaskFailure, } from "../contracts/index.js";
2
+ import { CleanupFailure } from "../environment/lifecycle.js";
3
+ import { ReapFailure } from "../environment/process.js";
4
+ import { ReapedGate } from "../verification/reaped.js";
2
5
  export { BlockedError };
6
+ /**
7
+ * Отказ, по которому судится попытка: у незавершённой очистки окружения —
8
+ * исходный отказ работы (`CleanupFailure.original`, через все вложенные
9
+ * очистки), иначе сам отказ.
10
+ */
11
+ export function failureOrigin(error) {
12
+ let origin = error;
13
+ while (origin instanceof CleanupFailure && origin.original)
14
+ origin = origin.original;
15
+ return origin;
16
+ }
3
17
  /**
4
18
  * Отказ провайдера, а не работы: он повторится на любой следующей выдаче.
5
19
  * Список узкий намеренно — временные ошибки сети сюда не входят.
@@ -22,6 +36,10 @@ const byCode = {
22
36
  BUDGET_EXHAUSTED: 'budget',
23
37
  };
24
38
  export function classifyFailure(error, message) {
39
+ // Незавершённая очистка не меняет класс отказа работы; без него это отказ
40
+ // окружения — ресурсы попытки не освобождены.
41
+ if (error instanceof CleanupFailure)
42
+ return error.original ? classifyFailure(error.original, message) : 'environment';
25
43
  if (error instanceof TaskFailure)
26
44
  return error.kind;
27
45
  // Приёмка отказала по правилу (нет доказательства, ревью, область): класс —
@@ -54,6 +72,8 @@ export function environmentCauseOf(error, message, kind) {
54
72
  return providerLimit(message) ? 'provider-limit' : 'provider-auth';
55
73
  if (kind !== 'environment')
56
74
  return 'none';
75
+ if (error instanceof CleanupFailure)
76
+ return error.original ? environmentCauseOf(error.original, message, kind) : 'cleanup';
57
77
  if (error instanceof TaskFailure && error.diagnosis)
58
78
  return error.diagnosis;
59
79
  if (transportFailure(message) ||
@@ -69,6 +89,12 @@ export function environmentCauseOf(error, message, kind) {
69
89
  * `Error` с исходным в `cause`.
70
90
  */
71
91
  export function withSuffix(failure, suffix) {
92
+ // Признак незавершённой очистки и неостановленных потомков сохраняется:
93
+ // по нему решаются сохранение деревьев и запрет повтора на дереве.
94
+ if (failure instanceof CleanupFailure ||
95
+ failure instanceof ReapedGate ||
96
+ failure instanceof ReapFailure)
97
+ return failure.extend(suffix);
72
98
  return failure instanceof TaskFailure
73
99
  ? new TaskFailure(failure.kind, `${failure.message}; ${suffix}`, failure.properties, failure.diagnosis, failure.contextLimit)
74
100
  : new Error(`${failure.message}; ${suffix}`, { cause: failure });
@@ -682,6 +682,19 @@ export declare class Engine {
682
682
  * поручения, политика не сменилась и хост не возражает.
683
683
  */
684
684
  withAttempt<T>(id: string, token: string, kind: TransactionKind, fn: (attempt: AttemptState, work: WorkState, tx: ExecutionTransaction) => NotPromise<T>): T;
685
+ /**
686
+ * Когда продление попытки последний раз проверяло политику и guards
687
+ * полностью: token, версия данных и момент проверки (D53).
688
+ */
689
+ private readonly leaseChecks;
690
+ /**
691
+ * Продление владения попыткой. У хранилища со строками аренды (D53) —
692
+ * условное продление одной строки: документ не читается и не пишется.
693
+ * Политика и guards, которые раньше проверяло каждое продление,
694
+ * проверяются полностью (`withAttempt`), когда сменилась версия данных
695
+ * или с прошлой полной проверки прошёл срок аренды: смена политики или
696
+ * отказ хоста по-прежнему прерывают идущую попытку.
697
+ */
685
698
  heartbeat(id: string, token: string): void;
686
699
  /** Причина неудавшегося продления: записывается первой и не затирается. Истёкший срок допустим, чужой токен — нет. */
687
700
  heartbeatFailed(id: string, token: string, reason: string): boolean;
@@ -1210,9 +1210,53 @@ export class Engine {
1210
1210
  return fn(attempt, work, tx);
1211
1211
  });
1212
1212
  }
1213
+ /**
1214
+ * Когда продление попытки последний раз проверяло политику и guards
1215
+ * полностью: token, версия данных и момент проверки (D53).
1216
+ */
1217
+ leaseChecks = new Map();
1218
+ /**
1219
+ * Продление владения попыткой. У хранилища со строками аренды (D53) —
1220
+ * условное продление одной строки: документ не читается и не пишется.
1221
+ * Политика и guards, которые раньше проверяло каждое продление,
1222
+ * проверяются полностью (`withAttempt`), когда сменилась версия данных
1223
+ * или с прошлой полной проверки прошёл срок аренды: смена политики или
1224
+ * отказ хоста по-прежнему прерывают идущую попытку.
1225
+ */
1213
1226
  heartbeat(id, token) {
1214
- this.withAttempt(id, token, 'heartbeat', (a, _w, tx) => {
1215
- tx.putAttempt({ ...a, leaseUntil: this.now() + this.policy.leaseMs });
1227
+ this.tx('heartbeat', (tx) => {
1228
+ if (!tx.renewLease || !tx.attemptLease || !tx.dataVersion) {
1229
+ this.withAttempt(id, token, 'heartbeat', (a, _w, inner) => {
1230
+ inner.putAttempt({ ...a, leaseUntil: this.now() + this.policy.leaseMs });
1231
+ });
1232
+ return;
1233
+ }
1234
+ const now = this.now();
1235
+ try {
1236
+ const lease = tx.attemptLease(id);
1237
+ if (!lease || lease.token !== token || lease.leaseUntil <= now)
1238
+ throw new HarnessError('LEASE_STALE', 'Устаревшая попытка: владение утрачено');
1239
+ if (lease.engineVersion !== this.version)
1240
+ throw new HarnessError('LEASE_STALE', `Попытку выдал движок ${lease.engineVersion ?? 'прежней версии'}, а работает ${this.version}: продолжение прежним token запрещено, нужна новая попытка`);
1241
+ const version = tx.dataVersion();
1242
+ const checked = this.leaseChecks.get(id);
1243
+ if (!checked ||
1244
+ checked.token !== token ||
1245
+ checked.dataVersion !== version ||
1246
+ now - checked.at >= this.policy.leaseMs) {
1247
+ // Полная проверка — та же, что у любой операции попытки.
1248
+ this.withAttempt(id, token, 'heartbeat', () => undefined);
1249
+ this.leaseChecks.set(id, { token, dataVersion: version, at: now });
1250
+ if (this.leaseChecks.size > 1000)
1251
+ this.leaseChecks.delete(this.leaseChecks.keys().next().value);
1252
+ }
1253
+ if (!tx.renewLease('attempt', id, token, lease.owner, lease.engineVersion, now + this.policy.leaseMs, now))
1254
+ throw new HarnessError('LEASE_STALE', 'Устаревшая попытка: владение утрачено');
1255
+ }
1256
+ catch (error) {
1257
+ this.leaseChecks.delete(id);
1258
+ throw error;
1259
+ }
1216
1260
  });
1217
1261
  }
1218
1262
  /** Причина неудавшегося продления: записывается первой и не затирается. Истёкший срок допустим, чужой токен — нет. */
@@ -82,12 +82,6 @@ export interface RunnerHooks {
82
82
  sha: string;
83
83
  }): void | Promise<void>;
84
84
  }
85
- /**
86
- * Исполнитель очереди. Один действующий controller; попытка проходит
87
- * реализацию, проверку области, gates и независимое ревью кандидата, затем
88
- * интеграцию с текущей принятой веткой, gates и ревью integration SHA и
89
- * приёмку с CAS продвижения target ref внутри транзакции приёмки.
90
- */
91
85
  export declare class Runner {
92
86
  readonly options: RunnerOptions;
93
87
  /** Предел git update-ref приёмки внутри транзакции; конечный и короче lease. */
@@ -302,6 +296,17 @@ export declare class Runner {
302
296
  * прошёл, `confirmed` — провал подтвердился и засчитывается как прежде).
303
297
  */
304
298
  private integrationGate;
299
+ /**
300
+ * Провал gate интеграции при неостановленных потомках. Если кандидат этот
301
+ * gate прошёл, а провал назван только ненулевым кодом выхода (`exitOnly`:
302
+ * ни упавшего или пропущенного теста, ни свойства, покрытия, отчёта,
303
+ * корпуса, ни правки HEAD или отслеживаемых файлов), это — перегрузка хоста
304
+ * (`ps` не уложился в свой предел, семейство D52), а не дефект: такой
305
+ * провал без потомков получил бы повтор, а повтора на этом дереве нет.
306
+ * Класс — `environment`/`process-reap`, не засчитывается. Названный провал
307
+ * остаётся `gate`.
308
+ */
309
+ private overloadedIntegration;
305
310
  /**
306
311
  * Gates фазы, которые исполняются; для остальных (gate с `when.paths`, чей
307
312
  * путь diff фазы не задел, — `gateDecisions`) записывается `not-applicable`.
@@ -17,7 +17,7 @@ import { alreadySatisfiedReviewOutputSchema, implementationOutputSchema, reviewO
17
17
  import { reviewInspection } from "../agents/inspect.js";
18
18
  import { reviewerRunsChecks } from "../agents/cli-adapter.js";
19
19
  import { gateProbePrompt, observeReproductions, assertProbeSpec, probeCommand, probeGates, probeLimits, probeRecord, readProbeJournal, recoverProbeLog, probeTool, } from "../agents/review-probe.js";
20
- import { GateTimeout, prepareWriterDependencies, draftTouchesInstall, runGate, writerDependenciesNote, writerDependencyGates, } from "../verification/gates.js";
20
+ import { GateTimeout, prepareWriterDependencies, ReapedGate, reapedFailure, draftTouchesInstall, runGate, writerDependenciesNote, writerDependencyGates, } from "../verification/gates.js";
21
21
  import { ActivityScope, activityScope } from "../environment/activity.js";
22
22
  import { StallSweep, StalledError, stallMessage, livenessPayload, } from "./stall-sweep.js";
23
23
  import { orderedScope } from "../verification/gate-scope.js";
@@ -27,7 +27,7 @@ import { assertDependencies, dependencyFreshness, removeSnapshots, snapshotDepen
27
27
  import { CleanupFailure, cleanupEnvironment } from "../environment/lifecycle.js";
28
28
  import { defaultResourceDatabase, withResources } from "../environment/resources.js";
29
29
  import { REQUIREMENT_GATE, assertRequirements } from "../verification/requirements.js";
30
- import { BlockedError, classifyFailure, environmentCauseOf, withSuffix } from "./classify.js";
30
+ import { BlockedError, classifyFailure, environmentCauseOf, failureOrigin, withSuffix, } from "./classify.js";
31
31
  import { TaskFailure } from "./failure.js";
32
32
  import { activeOf, namesFailingCases } from "./engine.js";
33
33
  import { prompt } from "./prompt.js";
@@ -54,6 +54,8 @@ const within = (path, prefixes) => prefixes.some((p) => p === '.' || path === p
54
54
  * интеграцию с текущей принятой веткой, gates и ревью integration SHA и
55
55
  * приёмку с CAS продвижения target ref внутри транзакции приёмки.
56
56
  */
57
+ /** Текст отказа о черновике, сохранённом только файлом. */
58
+ const artifactOnly = (patch) => `изменения попытки сохранены только файлом ${patch} (автоматически не применяются: потомки могли ещё писать в дерево)`;
57
59
  export class Runner {
58
60
  options;
59
61
  /** Предел git update-ref приёмки внутри транзакции; конечный и короче lease. */
@@ -813,7 +815,13 @@ export class Runner {
813
815
  * них, а не с пустого дерева. Не удалось сохранить — попытка просто
814
816
  * начнётся заново.
815
817
  */
816
- async keepDraft(attempt, work, artifacts) {
818
+ async keepDraft(attempt, work, artifacts,
819
+ /**
820
+ * Записать черновик в попытку (его продолжит следующая). `false` — только
821
+ * файл в artifacts: дерево могли ещё менять неостановленные потомки, и
822
+ * автоматически такой снимок не применяется.
823
+ */
824
+ record = true) {
817
825
  if (attempt.candidateSha || !attempt.worktree || !attempt.baseSha || !work.approvedDigest)
818
826
  return;
819
827
  try {
@@ -828,6 +836,8 @@ export class Runner {
828
836
  const text = await readFile(patch, 'utf8');
829
837
  if (!text.trim() || text.length > 5_000_000)
830
838
  return;
839
+ if (!record)
840
+ return patch;
831
841
  const files = (await git(attempt.worktree, 'diff', '--cached', '--name-only', attempt.baseSha, ...scope))
832
842
  .split('\n')
833
843
  .filter(Boolean);
@@ -838,6 +848,7 @@ export class Runner {
838
848
  spec: work.approvedDigest,
839
849
  contracts: Object.fromEntries(work.order.contracts.map((c) => [c.id, c.digest])),
840
850
  });
851
+ return patch;
841
852
  }
842
853
  catch {
843
854
  /* Черновик — удобство, а не условие: без него попытка начнётся с нуля. */
@@ -1199,7 +1210,11 @@ export class Runner {
1199
1210
  await this.candidateGate(attempt, cwd, sha, gate, artifacts, signal, execution, recheck).catch((error) => {
1200
1211
  // Без изменений непрошедший gate значит одно: работа не
1201
1212
  // сделана, — это пустой результат, а не дефект кода.
1202
- if (sha !== base || !(error instanceof TaskFailure))
1213
+ // Отказ среды (в том числе неостановленные потомки) остаётся
1214
+ // отказом среды и без изменений: о работе он не говорит.
1215
+ if (sha !== base ||
1216
+ !(error instanceof TaskFailure) ||
1217
+ error.kind === 'environment')
1203
1218
  throw error;
1204
1219
  throw new TaskFailure('empty-result', 'Изменений нет, а проверки задачи на базе не проходят: ' + error.message);
1205
1220
  });
@@ -1228,6 +1243,10 @@ export class Runner {
1228
1243
  // Незавершённая очистка окружения: рабочие деревья и снимки — входы её
1229
1244
  // повторения (`environment.json` ссылается на них), их нельзя убирать.
1230
1245
  preserve = error instanceof CleanupFailure;
1246
+ // Класс, свойства и вопрос — исходного отказа работы, а не очистки.
1247
+ const origin = failureOrigin(error);
1248
+ // Потомки прерванной или упавшей команды не остановлены.
1249
+ const reapedTree = reapedFailure(origin);
1231
1250
  // Прерывание по лимиту времени называется лимитом времени, что бы ни выбросила прерванная операция.
1232
1251
  const expired = controller.signal.aborted &&
1233
1252
  controller.signal.reason?.name === 'TimeoutError';
@@ -1238,7 +1257,7 @@ export class Runner {
1238
1257
  ? controller.signal.reason.message
1239
1258
  : undefined;
1240
1259
  const message = stalled ??
1241
- (expired && !(error instanceof TaskFailure)
1260
+ (expired && !(origin instanceof TaskFailure)
1242
1261
  ? `Исчерпан лимит времени попытки (${Math.round(this.policy.runTimeoutMs / 1000)} с)`
1243
1262
  : error instanceof Error
1244
1263
  ? error.message
@@ -1249,8 +1268,11 @@ export class Runner {
1249
1268
  const shutdown = controller.signal.aborted && this.jobs.get(attempt.id)?.shutdown === true;
1250
1269
  if (shutdown)
1251
1270
  try {
1252
- await this.keepDraft(attempt, await this.workOf(attempt), artifacts);
1253
- const message = 'Попытку прервала штатная остановка controller; поручение возвращено в очередь и продолжится с кандидата или черновика';
1271
+ // Неостановленные потомки прерванной команды могли ещё писать в
1272
+ // дерево: его изменения — только файлом, не черновиком следующей.
1273
+ const saved = await this.keepDraft(attempt, await this.workOf(attempt), artifacts, !reapedTree);
1274
+ const message = 'Попытку прервала штатная остановка controller; поручение возвращено в очередь и продолжится с кандидата или черновика' +
1275
+ (reapedTree && saved ? `; ${artifactOnly(saved)}` : '');
1254
1276
  const failed = this.engine.fail(attempt.id, attempt.token, message, {
1255
1277
  kind: 'environment',
1256
1278
  interrupted: true,
@@ -1272,13 +1294,28 @@ export class Runner {
1272
1294
  try {
1273
1295
  const kind = stalled
1274
1296
  ? 'stalled'
1275
- : expired && !(error instanceof TaskFailure)
1297
+ : expired && !(origin instanceof TaskFailure)
1276
1298
  ? 'timeout'
1277
1299
  : classifyFailure(error, message);
1278
1300
  // Незакоммиченная работа сохраняется при любом отказе до кандидата:
1279
1301
  // по времени, «не закончил», обрыв. Иначе повтор начинал с пустого
1280
1302
  // дерева и тратил попытку на сделанное.
1281
- if (kind !== 'provider-auth')
1303
+ // Неостановленные потомки (вызов runtime, установка зависимостей)
1304
+ // могут ещё писать в дерево: снимок черновика был бы снимком чужой
1305
+ // записи на ходу. Попытка — отказ среды без черновика; следующая
1306
+ // начинает с базы в новом дереве.
1307
+ const cause = environmentCauseOf(stalled ? undefined : error, message, kind);
1308
+ let reported = message;
1309
+ // Неостановленные потомки могли ещё писать в дерево — при любом
1310
+ // исходе, в том числе зависании: черновик не продолжается следующей
1311
+ // попыткой. Изменения сохраняются только файлом — их можно разобрать
1312
+ // и применить вручную.
1313
+ if (cause === 'process-reap' || reapedTree) {
1314
+ const saved = await this.keepDraft(attempt, await this.workOf(attempt), artifacts, false);
1315
+ if (saved)
1316
+ reported += `; ${artifactOnly(saved)}`;
1317
+ }
1318
+ else if (kind !== 'provider-auth')
1282
1319
  await this.keepDraft(attempt, await this.workOf(attempt), artifacts);
1283
1320
  // Пример reviewer — гипотеза; эталон решает, станет ли он обязательным:
1284
1321
  // подтверждение идёт до записи отказа, и принятие новой версии корпуса
@@ -1286,25 +1323,25 @@ export class Runner {
1286
1323
  if (kind === 'review' && this.policy.approvalMode === 'agent')
1287
1324
  await this.confirmReproductions(attempt).catch(() => undefined);
1288
1325
  const failure = {
1289
- ...(!stalled && error instanceof TaskFailure && error.properties
1290
- ? { properties: error.properties }
1326
+ ...(!stalled && origin instanceof TaskFailure && origin.properties
1327
+ ? { properties: origin.properties }
1291
1328
  : {}),
1292
1329
  kind,
1293
- ...(!stalled && error instanceof TaskFailure && error.contextLimit
1294
- ? { contextLimit: error.contextLimit }
1330
+ ...(!stalled && origin instanceof TaskFailure && origin.contextLimit
1331
+ ? { contextLimit: origin.contextLimit }
1295
1332
  : {}),
1296
- cause: environmentCauseOf(stalled ? undefined : error, message, kind),
1297
- blocked: (error instanceof BlockedError ||
1333
+ cause,
1334
+ blocked: (origin instanceof BlockedError ||
1298
1335
  kind === 'provider-auth' ||
1299
1336
  // Отказ до работы с известной причиной preflight: не засчитывается.
1300
- (error instanceof TaskFailure && error.diagnosis === 'preflight')) &&
1337
+ (origin instanceof TaskFailure && origin.diagnosis === 'preflight')) &&
1301
1338
  !attempt.candidateSha,
1302
1339
  ...(heartbeatCause ? { heartbeatCause } : {}),
1303
1340
  };
1304
- const input = !stalled && error instanceof TaskFailure ? error.input : undefined;
1305
- let recorded = { kind, message };
1341
+ const input = !stalled && origin instanceof TaskFailure ? origin.input : undefined;
1342
+ let recorded = { kind, message: reported };
1306
1343
  try {
1307
- this.engine.fail(attempt.id, attempt.token, message, {
1344
+ this.engine.fail(attempt.id, attempt.token, reported, {
1308
1345
  ...failure,
1309
1346
  ...(input ? { input } : {}),
1310
1347
  });
@@ -1318,7 +1355,7 @@ export class Runner {
1318
1355
  throw refused;
1319
1356
  recorded = {
1320
1357
  kind: kind === 'needs-input' ? 'unfinished' : kind,
1321
- message: `${message}. Вопрос исполнителя не записан: ${(refused instanceof Error ? refused.message : String(refused)).slice(0, 300)}`,
1358
+ message: `${reported}. Вопрос исполнителя не записан: ${(refused instanceof Error ? refused.message : String(refused)).slice(0, 300)}`,
1322
1359
  };
1323
1360
  this.engine.fail(attempt.id, attempt.token, recorded.message, {
1324
1361
  ...failure,
@@ -1693,9 +1730,13 @@ export class Runner {
1693
1730
  await this.gate(attempt, cwd, sha, 'integration', gate, artifacts, signal, execution);
1694
1731
  }
1695
1732
  catch (error) {
1733
+ if (!signal.aborted && error instanceof ReapedGate && error.kind === 'gate')
1734
+ throw this.overloadedIntegration(attempt, sha, gate, error);
1696
1735
  if (!budget.recheck || signal.aborted || !(error instanceof TaskFailure))
1697
1736
  throw error;
1698
- if (error.kind !== 'gate')
1737
+ // Потомки gate не остановлены: повтор на том же дереве рядом с живым
1738
+ // писателем не проводится, какой бы ни был класс.
1739
+ if (error.kind !== 'gate' || reapedFailure(error))
1699
1740
  throw error;
1700
1741
  const { failed, candidatePassed, spent } = this.engine.read((v) => {
1701
1742
  const evidence = v.attempt(attempt.id)?.evidence ?? [];
@@ -1724,6 +1765,33 @@ export class Runner {
1724
1765
  await this.gate(attempt, cwd, sha, 'integration', gate, artifacts, signal, execution, undefined, failed.id);
1725
1766
  }
1726
1767
  }
1768
+ /**
1769
+ * Провал gate интеграции при неостановленных потомках. Если кандидат этот
1770
+ * gate прошёл, а провал назван только ненулевым кодом выхода (`exitOnly`:
1771
+ * ни упавшего или пропущенного теста, ни свойства, покрытия, отчёта,
1772
+ * корпуса, ни правки HEAD или отслеживаемых файлов), это — перегрузка хоста
1773
+ * (`ps` не уложился в свой предел, семейство D52), а не дефект: такой
1774
+ * провал без потомков получил бы повтор, а повтора на этом дереве нет.
1775
+ * Класс — `environment`/`process-reap`, не засчитывается. Названный провал
1776
+ * остаётся `gate`.
1777
+ */
1778
+ overloadedIntegration(attempt, sha, gate, error) {
1779
+ const { failed, candidatePassed } = this.engine.read((v) => {
1780
+ const evidence = v.attempt(attempt.id)?.evidence ?? [];
1781
+ const own = (e, phase, at) => e.kind === 'test' && e.gate === gate.id && e.phase === phase && e.sha === at && !e.consumer;
1782
+ return {
1783
+ failed: evidence.findLast((e) => own(e, 'integration', sha)),
1784
+ candidatePassed: evidence.findLast((e) => own(e, 'candidate', attempt.candidateSha))?.passed === true,
1785
+ };
1786
+ });
1787
+ const named = !failed ||
1788
+ namesFailingCases(failed) ||
1789
+ (failed.tests ?? []).some((t) => t.status === 'failed') ||
1790
+ (error.properties?.bound.length ?? 0) + (error.properties?.unbound.length ?? 0) > 0;
1791
+ if (!error.exitOnly || named || !candidatePassed)
1792
+ return error;
1793
+ return new ReapedGate('environment', error.message, undefined, 'process-reap');
1794
+ }
1727
1795
  /**
1728
1796
  * Gates фазы, которые исполняются; для остальных (gate с `when.paths`, чей
1729
1797
  * путь diff фазы не задел, — `gateDecisions`) записывается `not-applicable`.
@@ -1955,7 +2023,7 @@ export class Runner {
1955
2023
  retained.worktrees.push({ checkout, dir });
1956
2024
  retained.snapshots.push(...dependencies.filter((d) => d.repositoryId !== provider));
1957
2025
  this.retained.set(attempt.id, retained);
1958
- throw new CleanupFailure(`${failure.message}; рабочие деревья проверки потребителя ${repo.id} сохранены для повторной очистки (${join(own, 'environment', 'environment.json')})`);
2026
+ throw failure.extend(`рабочие деревья проверки потребителя ${repo.id} сохранены для повторной очистки (${join(own, 'environment', 'environment.json')})`);
1959
2027
  }
1960
2028
  // Очистка — обязательная часть проверки: её отказ не скрывается и не
1961
2029
  // заслоняется отказом самой проверки.
@@ -0,0 +1,12 @@
1
+ /** Снимок нагрузки хоста; объект — чтобы тест мог подменить чтение. */
2
+ export declare const hostLoad: {
3
+ read: () => HostLoad;
4
+ };
5
+ export interface HostLoad {
6
+ /** Средняя нагрузка за минуту (`os.loadavg()[0]`; на Windows — 0). */
7
+ load1: number;
8
+ /** Доступные процессу ядра. */
9
+ cpus: number;
10
+ }
11
+ /** Нагрузка хоста словами — свидетельство в тексте отказа. */
12
+ export declare const loadText: (load: HostLoad) => string;
@@ -0,0 +1,7 @@
1
+ import { availableParallelism, loadavg } from 'node:os';
2
+ /** Снимок нагрузки хоста; объект — чтобы тест мог подменить чтение. */
3
+ export const hostLoad = {
4
+ read: () => ({ load1: loadavg()[0] ?? 0, cpus: Math.max(1, availableParallelism()) }),
5
+ };
6
+ /** Нагрузка хоста словами — свидетельство в тексте отказа. */
7
+ export const loadText = (load) => `нагрузка хоста ${Math.round(load.load1 * 10) / 10} на ${load.cpus} ядер`;
@@ -5,9 +5,20 @@ export { redactor } from './redaction.ts';
5
5
  type Environment = z.infer<typeof environmentSchema>;
6
6
  type Lifecycle = z.infer<typeof lifecycleSchema>;
7
7
  type Step = z.infer<typeof stepSchema>;
8
- /** Отказ обязательной очистки окружения: приёмка с ним не происходит. */
8
+ /**
9
+ * Отказ обязательной очистки окружения: приёмка с ним не происходит.
10
+ * Исходный отказ работы, если он был, — `cause`: класс и причина попытки —
11
+ * его (`classifyFailure`), очистка лишь дописана к тексту. Без исходного
12
+ * отказа это отказ окружения `cleanup`: ресурсы попытки не освобождены, о
13
+ * коде это ничего не говорит.
14
+ */
9
15
  export declare class CleanupFailure extends Error {
10
16
  name: string;
17
+ constructor(message: string, original?: Error);
18
+ /** Исходный отказ работы, если он был. */
19
+ get original(): Error | undefined;
20
+ /** Тот же отказ с дописанной причиной; исходный отказ сохраняется. */
21
+ extend(suffix: string): CleanupFailure;
11
22
  }
12
23
  /** Жив ли процесс (сигнал 0 не доставляется, только проверяется). */
13
24
  export declare function processAlive(pid: number): boolean;
@@ -6,9 +6,26 @@ import { protectedChanges, protectedSnapshot, SandboxPolicyError } from "./isola
6
6
  import { command } from "./process.js";
7
7
  import { redactor } from "./redaction.js";
8
8
  export { redactor } from "./redaction.js";
9
- /** Отказ обязательной очистки окружения: приёмка с ним не происходит. */
9
+ /**
10
+ * Отказ обязательной очистки окружения: приёмка с ним не происходит.
11
+ * Исходный отказ работы, если он был, — `cause`: класс и причина попытки —
12
+ * его (`classifyFailure`), очистка лишь дописана к тексту. Без исходного
13
+ * отказа это отказ окружения `cleanup`: ресурсы попытки не освобождены, о
14
+ * коде это ничего не говорит.
15
+ */
10
16
  export class CleanupFailure extends Error {
11
17
  name = 'CleanupFailure';
18
+ constructor(message, original) {
19
+ super(message, original ? { cause: original } : undefined);
20
+ }
21
+ /** Исходный отказ работы, если он был. */
22
+ get original() {
23
+ return this.cause instanceof Error ? this.cause : undefined;
24
+ }
25
+ /** Тот же отказ с дописанной причиной; исходный отказ сохраняется. */
26
+ extend(suffix) {
27
+ return new CleanupFailure(`${this.message}; ${suffix}`, this.original);
28
+ }
12
29
  }
13
30
  /** Жив ли процесс (сигнал 0 не доставляется, только проверяется). */
14
31
  export function processAlive(pid) {
@@ -252,7 +269,7 @@ export async function withEnvironment(lifecycle, cwd, dir, execution, signal, ac
252
269
  }
253
270
  catch (error) {
254
271
  receipt.status = 'cleanup-failed';
255
- failure = new CleanupFailure(`${failure instanceof Error ? failure.message + '; ' : ''}Очистка окружения не завершена: ${error instanceof Error ? error.message : String(error)}`);
272
+ failure = new CleanupFailure(`${failure instanceof Error ? failure.message + '; ' : ''}Очистка окружения не завершена: ${error instanceof Error ? error.message : String(error)}`, failure);
256
273
  }
257
274
  await writeFile(receiptPath, JSON.stringify(receipt, null, 2));
258
275
  if (failure)
@@ -1,5 +1,54 @@
1
1
  import { type Redactor } from './redaction.ts';
2
- import type { Activity, RuntimeDiagnostics } from '../contracts/index.ts';
2
+ import { TaskFailure, type Activity, type RuntimeDiagnostics } from '../contracts/index.ts';
3
+ /**
4
+ * Сдерживаемая команда завершилась, но её потомков не удалось остановить или
5
+ * хотя бы пересчитать (`ps` не ответил под нагрузкой хоста). О коде это
6
+ * ничего не говорит: класс — отказ окружения (`process-reap`), попытка не
7
+ * засчитывается. Сдерживание не ослабляется: результата команды нет, и
8
+ * вызывающий не принимает её исход — потомок, возможно, ещё работает в её
9
+ * каталогах.
10
+ */
11
+ export declare class ReapFailure extends TaskFailure {
12
+ /** Пережившие остановку PID; пусто, если перечень так и не получен. */
13
+ readonly survivors: number[];
14
+ /** Почему перечень процессов не получен; нет — перечень был. */
15
+ readonly inventory: string | undefined;
16
+ /**
17
+ * Исход самой команды (код, вывод), если она завершилась: провал,
18
+ * который она назвала, — свидетельство о коде и при неостановленных
19
+ * потомках. Принимать его успехом нельзя.
20
+ */
21
+ readonly result?: CommandResult | undefined;
22
+ constructor(message: string,
23
+ /** Пережившие остановку PID; пусто, если перечень так и не получен. */
24
+ survivors: number[],
25
+ /** Почему перечень процессов не получен; нет — перечень был. */
26
+ inventory: string | undefined,
27
+ /**
28
+ * Исход самой команды (код, вывод), если она завершилась: провал,
29
+ * который она назвала, — свидетельство о коде и при неостановленных
30
+ * потомках. Принимать его успехом нельзя.
31
+ */
32
+ result?: CommandResult | undefined);
33
+ /** Тот же отказ с дописанной причиной (например, неубранными каталогами). */
34
+ extend(suffix: string): ReapFailure;
35
+ }
36
+ /**
37
+ * Отказ остановки потомков завершившейся команды — один текст у всех, кто
38
+ * сдерживает команды (и у хоста со своим запуском): команда, её PID и
39
+ * выход, что не остановлено (PID или почему нет перечня), нагрузка хоста.
40
+ */
41
+ export declare function reapFailure(outcome: {
42
+ /** Что за команда: ID gate, runtime и задача. */
43
+ label: string;
44
+ pid: number | undefined;
45
+ code: number | null;
46
+ signal: NodeJS.Signals | null;
47
+ survivors: number[];
48
+ inventory?: string | undefined;
49
+ redact?: (value: string) => string;
50
+ result?: CommandResult;
51
+ }): ReapFailure;
3
52
  export interface CommandResult {
4
53
  code: number;
5
54
  stdout: string;
@@ -67,3 +116,24 @@ export declare function gitRawOutput(cwd: string, ...args: string[]): Promise<st
67
116
  */
68
117
  export declare function gitBlobs(cwd: string, ids: readonly string[]): Promise<Map<string, Buffer<ArrayBufferLike>>>;
69
118
  export declare function git(cwd: string, ...args: string[]): Promise<string>;
119
+ /**
120
+ * Вывод системной утилиты или причина, по которой его нет. Не блокирует
121
+ * event loop. Локаль фиксирована (`osToolEnv`): вывод разбирается.
122
+ */
123
+ declare function outcome(command: string, args: string[], timeout: number, partial?: number): Promise<{
124
+ stdout: string;
125
+ } | {
126
+ error: string;
127
+ }>;
128
+ /** Процессы пользователя, в окружении которых есть метка. */
129
+ declare function marked(mark: string): Promise<number[]>;
130
+ /**
131
+ * Перечень процессов для остановки потомков; объект — чтобы тест мог
132
+ * подменить его отказ.
133
+ */
134
+ export declare const processInventory: {
135
+ marked: typeof marked;
136
+ /** Запуск системной утилиты перечня (`ps`, `lsof`). */
137
+ tool: typeof outcome;
138
+ };
139
+ export {};