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
@@ -746,7 +746,8 @@ export declare class Harness {
746
746
  /**
747
747
  * Состояние очереди, графов и поручений. С `detail` — ещё снимок
748
748
  * наблюдателя: почему стоит выдача (`queueStop` и `queuePause`) и активные
749
- * попытки (`attemptView`); без него ответ прежний.
749
+ * попытки (`attemptView`); без него ответ прежний. Та же функция над
750
+ * движком и политикой хоста — `statusOf`.
750
751
  */
751
752
  status(graphId?: string, options?: {
752
753
  detail?: boolean;
@@ -767,7 +768,7 @@ export declare class Harness {
767
768
  } | {
768
769
  code?: "INVALID_INPUT" | "UNSUPPORTED_COMMAND" | "UNSUPPORTED_VERSION" | "GRAPH_CYCLE" | "GRAPH_UNKNOWN_DEPENDENCY" | "GRAPH_DUPLICATE_ID" | "GATE_UNKNOWN" | "GATE_GROUP_CYCLE" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "RESPONSE_TOO_LARGE" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "LEASE_STALE" | "CONTROLLER_BUSY" | "PAUSED" | "NOT_READY" | "SCOPE_VIOLATION" | "GATE_FAILED" | "REVIEW_REJECTED" | "BUDGET_EXHAUSTED" | "BUDGET_UNKNOWN" | "ATTEMPTS_EXHAUSTED" | "REVISION_CONFLICT" | "CANCELLED" | "NOT_FOUND" | "PATH_CONFLICT" | "STATE_VERSION_UNSUPPORTED" | "RUNTIME_UNAVAILABLE" | "REVIEW_PROTOCOL_INVALID" | "SANDBOX_UNAVAILABLE" | "GIT_FAILED" | "STORAGE_FAILED" | "DELIVERY_FAILED" | "INTERNAL" | undefined;
769
770
  cause?: "gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | "runtime-missing" | "controller-busy" | "operator-pause" | "approval-required" | "not-ready" | undefined;
770
- actor?: import("../projections/enums.ts").Actor | undefined;
771
+ actor?: import("../index.ts").Actor | undefined;
771
772
  action?: "none" | "wait" | "retry" | "review-plan" | "diagnose-failure" | "reset-attempts" | "raise-budget" | "replan-dependents" | "recovery-decision" | "user-decision" | "resume-queue" | "fix-environment" | "fix-access" | undefined;
772
773
  failures?: ("gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead")[] | undefined;
773
774
  operation?: string | undefined;
@@ -776,13 +777,13 @@ export declare class Harness {
776
777
  paused: boolean;
777
778
  reason?: import("../contracts/execution.ts").PauseReason;
778
779
  };
779
- attempts: import("../projections/attempt.ts").AttemptView[];
780
+ attempts: import("../index.ts").AttemptView[];
780
781
  } | undefined;
781
782
  budgets: {
782
783
  onUnknown: "continue" | "stop";
783
784
  budgets: {
784
785
  reason?: string | undefined;
785
- scope: import("../engine/budget.ts").BudgetScope;
786
+ scope: import("../index.ts").BudgetScope;
786
787
  state: "exceeded" | "undetermined" | "within";
787
788
  limit: {
788
789
  usd?: number;
@@ -885,7 +886,7 @@ export declare class Harness {
885
886
  } | {
886
887
  code?: "INVALID_INPUT" | "UNSUPPORTED_COMMAND" | "UNSUPPORTED_VERSION" | "GRAPH_CYCLE" | "GRAPH_UNKNOWN_DEPENDENCY" | "GRAPH_DUPLICATE_ID" | "GATE_UNKNOWN" | "GATE_GROUP_CYCLE" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "RESPONSE_TOO_LARGE" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "LEASE_STALE" | "CONTROLLER_BUSY" | "PAUSED" | "NOT_READY" | "SCOPE_VIOLATION" | "GATE_FAILED" | "REVIEW_REJECTED" | "BUDGET_EXHAUSTED" | "BUDGET_UNKNOWN" | "ATTEMPTS_EXHAUSTED" | "REVISION_CONFLICT" | "CANCELLED" | "NOT_FOUND" | "PATH_CONFLICT" | "STATE_VERSION_UNSUPPORTED" | "RUNTIME_UNAVAILABLE" | "REVIEW_PROTOCOL_INVALID" | "SANDBOX_UNAVAILABLE" | "GIT_FAILED" | "STORAGE_FAILED" | "DELIVERY_FAILED" | "INTERNAL" | undefined;
887
888
  cause?: "gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | "runtime-missing" | "controller-busy" | "operator-pause" | "approval-required" | "not-ready" | undefined;
888
- actor?: import("../projections/enums.ts").Actor | undefined;
889
+ actor?: import("../index.ts").Actor | undefined;
889
890
  action?: "none" | "wait" | "retry" | "review-plan" | "diagnose-failure" | "reset-attempts" | "raise-budget" | "replan-dependents" | "recovery-decision" | "user-decision" | "resume-queue" | "fix-environment" | "fix-access" | undefined;
890
891
  failures?: ("gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead")[] | undefined;
891
892
  operation?: string | undefined;
@@ -894,7 +895,7 @@ export declare class Harness {
894
895
  paused: boolean;
895
896
  reason?: import("../contracts/execution.ts").PauseReason;
896
897
  };
897
- attempts: import("../projections/attempt.ts").AttemptView[];
898
+ attempts: import("../index.ts").AttemptView[];
898
899
  } | undefined;
899
900
  budgets?: undefined;
900
901
  graphs: {
@@ -966,7 +967,6 @@ export declare class Harness {
966
967
  } | undefined;
967
968
  };
968
969
  };
969
- private statusDetail;
970
970
  /**
971
971
  * Отчёт об эффекте (`valueReport`) по состоянию этого каталога: только
972
972
  * чтение; пути evidence — относительно каталога состояния.
@@ -1120,6 +1120,33 @@ export declare class Harness {
1120
1120
  retries: number | null;
1121
1121
  resets: number | null;
1122
1122
  baseMoves: number | null;
1123
+ recorded: {
1124
+ from: string;
1125
+ bound: "exact" | "lower";
1126
+ retries: {
1127
+ operator: number;
1128
+ recovery: number;
1129
+ host: number;
1130
+ };
1131
+ resets: {
1132
+ operator: number;
1133
+ recovery: number;
1134
+ host: number;
1135
+ };
1136
+ cancellations: {
1137
+ operator: number;
1138
+ graph: number;
1139
+ host: number;
1140
+ };
1141
+ cancelledWithoutAttempt: number;
1142
+ baseMoves: {
1143
+ operator: number;
1144
+ controller: number;
1145
+ host: number;
1146
+ };
1147
+ baseMovesBound: "lower";
1148
+ gaps: number;
1149
+ } | null;
1123
1150
  };
1124
1151
  approvals: {
1125
1152
  operator: number;
@@ -1283,7 +1310,16 @@ export declare class Harness {
1283
1310
  };
1284
1311
  setupCheckFailures: number;
1285
1312
  timeLimit: number;
1286
- causes: null;
1313
+ causes: {
1314
+ rows: {
1315
+ cause: "preflight" | "transport" | "none" | "other" | "provider-auth" | "stalled" | "shutdown" | "sandbox-launch" | "sandbox-network" | "sandbox-filesystem" | "sandbox-policy" | "dependency-network" | "provider-limit" | "lease-expired";
1316
+ count: number;
1317
+ counted: number;
1318
+ }[];
1319
+ diagnosed: number;
1320
+ undiagnosed: number;
1321
+ bound: "exact" | "lower";
1322
+ } | null;
1287
1323
  neutral: {
1288
1324
  costBound: "exact" | "unknown" | "lower" | "upper";
1289
1325
  attempts: number;
@@ -1,10 +1,9 @@
1
1
  import { execFileSync } from 'node:child_process';
2
2
  import { existsSync, mkdirSync } from 'node:fs';
3
3
  import { isAbsolute, join, resolve } from 'node:path';
4
- import { executionDigest, API_VERSION, HarnessError, STATE_VERSION, WORKSPACE_OWNER, contextDigest, contextIssues, digestOf, workGraphDigest, } from "../contracts/index.js";
4
+ import { executionDigest, API_VERSION, HarnessError, WORKSPACE_OWNER, contextDigest, contextIssues, digestOf, workGraphDigest, } from "../contracts/index.js";
5
5
  import { cliAdapter } from "../agents/cli-adapter.js";
6
6
  import { Engine } from "../engine/engine.js";
7
- import { budgetOverview } from "../engine/budget.js";
8
7
  import { runResult } from "../engine/result.js";
9
8
  import { repairDecision } from "../engine/repair.js";
10
9
  import { Runner } from "../engine/runner.js";
@@ -13,8 +12,7 @@ import { HARNESS_VERSION } from "../package.js";
13
12
  import { SqliteExecutionStore } from "../storage/sqlite.js";
14
13
  import { validateInputs } from "../validate.js";
15
14
  import { WorkflowQueue } from "./workflow.js";
16
- import { nextRunControl } from "../explain/state.js";
17
- import { CLIP_DIAGNOSTIC, attemptView, clipText, queuePause, queueStop, } from "../projections/index.js";
15
+ import { statusOf } from "./status.js";
18
16
  import { technicalReview } from "./review.js";
19
17
  import { policySourceChanged } from "./provenance.js";
20
18
  import { JointRunner } from "../engine/joint-runner.js";
@@ -563,7 +561,8 @@ export class Harness {
563
561
  if (r.status === 'retry' && ['failed', 'cancelled'].includes(work.status)) {
564
562
  if (work.status === 'cancelled')
565
563
  throw new Error(`${workId}: поручение отменено человеком`);
566
- this.engine.retry(workId);
564
+ // Повтор по решению оператора — действие человека; по решению ведущего — восстановление.
565
+ this.engine.retry(workId, undefined, r.decision?.source.kind === 'operator' ? 'operator' : 'recovery');
567
566
  return true;
568
567
  }
569
568
  if (r.status === 'retry' || r.status === 'retrying')
@@ -584,7 +583,7 @@ export class Harness {
584
583
  if (!decided || decided.action === 'stop')
585
584
  return decided;
586
585
  this.workflows.repair(job, `repair:${decided.kind}`, () => {
587
- this.engine.retry(decided.workId);
586
+ this.engine.retry(decided.workId, undefined, 'recovery');
588
587
  // Повтор признал причину разовой: своя причина паузы снимается. Выдача
589
588
  // возвращается, только когда не осталось ни одной; пауза человека
590
589
  // не снимается вовсе.
@@ -602,98 +601,11 @@ export class Harness {
602
601
  /**
603
602
  * Состояние очереди, графов и поручений. С `detail` — ещё снимок
604
603
  * наблюдателя: почему стоит выдача (`queueStop` и `queuePause`) и активные
605
- * попытки (`attemptView`); без него ответ прежний.
604
+ * попытки (`attemptView`); без него ответ прежний. Та же функция над
605
+ * движком и политикой хоста — `statusOf`.
606
606
  */
607
607
  status(graphId, options = {}) {
608
- return this.engine.read((v) => ({
609
- stateVersion: STATE_VERSION,
610
- control: v.control(),
611
- ...(v.controller() ? { controller: v.controller() } : {}),
612
- graphs: v
613
- .graphs()
614
- .filter((g) => !graphId || g.id === graphId)
615
- .map((g) => ({
616
- id: g.id,
617
- digest: g.digest,
618
- source: g.graph.source,
619
- approved: g.approval?.digest === g.digest,
620
- })),
621
- works: v.works(graphId).map((w) => ({
622
- id: w.id,
623
- graphId: w.graphId,
624
- status: w.status,
625
- attempt: w.attempt,
626
- ...(w.activeRunId ? { activeRunId: w.activeRunId } : {}),
627
- ...((a) => a?.status === 'active' && a.liveness && a.liveness.state !== 'active'
628
- ? { liveness: a.liveness.state }
629
- : {})(w.activeRunId ? v.attempt(w.activeRunId) : undefined),
630
- ...(w.resultSha ? { resultSha: w.resultSha } : {}),
631
- blockers: this.engine.blockers(w, v),
632
- })),
633
- ...((budgets) => (budgets ? { budgets } : {}))(budgetOverview(this.engine.budgetContext(), v)),
634
- ...(options.detail ? { detail: this.statusDetail(v, graphId) } : {}),
635
- }));
636
- }
637
- statusDetail(v, graphId) {
638
- const now = this.engine.clock();
639
- const control = v.control();
640
- const works = v.works(graphId);
641
- const attempts = v.works().flatMap((w) => v.attempts(w.id));
642
- // Последний отказ классов паузы runtime — её подробность (как `queueStop`
643
- // хоста по ошибкам планировщика): порядок — по времени завершения.
644
- const failures = new Set(control.pauseFailures ?? []);
645
- const errors = attempts
646
- .filter((a) => a.status === 'failed' && a.failureKind && failures.has(a.failureKind))
647
- .sort((a, b) => (a.finishedAt ?? '').localeCompare(b.finishedAt ?? ''))
648
- .map((a, i) => ({ seq: i + 1, ...(a.error ? { message: a.error } : {}) }));
649
- const stop = queueStop({
650
- paused: control.paused,
651
- ...(control.pauseReason ? { pauseReason: control.pauseReason } : {}),
652
- errors,
653
- });
654
- const repositoryGates = (id) => this.policy.repositories.find((r) => r.id === id)?.gates.map((g) => g.id);
655
- // Пауза, которую снимет следующий run, глазами explain: выдача не стоит,
656
- // поручения ждут controller.
657
- const queue = nextRunControl(this, v).lifted
658
- ? {
659
- paused: true,
660
- ...(control.pauseReason ? { reason: control.pauseReason } : {}),
661
- detail: 'Паузу снимет следующий harness run',
662
- ...(control.pausedAt ? { since: control.pausedAt } : {}),
663
- ...(control.pauseOperation ? { operation: control.pauseOperation } : {}),
664
- liftedByRun: true,
665
- code: 'NOT_READY',
666
- cause: 'not-ready',
667
- actor: 'controller',
668
- action: 'wait',
669
- }
670
- : {
671
- ...stop,
672
- ...(stop.detail ? { detail: clipText(stop.detail, CLIP_DIAGNOSTIC) } : {}),
673
- ...(control.paused && control.pausedAt ? { since: control.pausedAt } : {}),
674
- ...(control.paused && control.pauseOperation
675
- ? { operation: control.pauseOperation }
676
- : {}),
677
- ...(control.paused && control.pauseFailures?.length
678
- ? { failures: [...control.pauseFailures] }
679
- : {}),
680
- ...(queuePause(control) ?? {}),
681
- };
682
- return {
683
- at: new Date(now).toISOString(),
684
- queue,
685
- attempts: works
686
- .map((w) => (w.activeRunId ? v.attempt(w.activeRunId) : undefined))
687
- .filter((a) => a?.status === 'active')
688
- .map((a) => {
689
- const gates = repositoryGates(a.repositoryId);
690
- return attemptView(a, {
691
- now,
692
- leaseMs: this.policy.leaseMs,
693
- ...(gates ? { repositoryGates: gates } : {}),
694
- });
695
- }),
696
- };
608
+ return statusOf(this, graphId, options);
697
609
  }
698
610
  /**
699
611
  * Отчёт об эффекте (`valueReport`) по состоянию этого каталога: только
@@ -0,0 +1,235 @@
1
+ import { type ExecutionPolicy } from '../contracts/index.ts';
2
+ import type { Engine } from '../engine/engine.ts';
3
+ /**
4
+ * Что читает `statusOf`: движок над хранилищем и политика исполнения.
5
+ * `Harness` удовлетворяет ему структурно; хост со своим `Engine` передаёт
6
+ * `{ engine, policy }`.
7
+ */
8
+ export interface StatusSource {
9
+ readonly engine: Engine;
10
+ readonly policy: ExecutionPolicy;
11
+ }
12
+ /**
13
+ * Состояние очереди, графов и поручений (`Harness.status`, `harness status`)
14
+ * над движком и политикой источника. С `detail` — ещё снимок наблюдателя:
15
+ * почему стоит выдача (`queueStop` и `queuePause`) и активные попытки
16
+ * (`attemptView`); без него ответ прежний. Только чтение, один `read`.
17
+ */
18
+ export declare function statusOf(source: StatusSource, graphId?: string, options?: {
19
+ detail?: boolean;
20
+ }): {
21
+ detail?: {
22
+ at: string;
23
+ queue: {
24
+ liftedByRun: true;
25
+ code: "NOT_READY";
26
+ cause: "not-ready";
27
+ actor: "controller";
28
+ action: "wait";
29
+ operation?: string | undefined;
30
+ since?: string | undefined;
31
+ detail: string;
32
+ reason?: "runtime" | "operator" | "shutdown" | "base-check" | "reconfigure" | undefined;
33
+ paused: boolean;
34
+ } | {
35
+ code?: "INVALID_INPUT" | "UNSUPPORTED_COMMAND" | "UNSUPPORTED_VERSION" | "GRAPH_CYCLE" | "GRAPH_UNKNOWN_DEPENDENCY" | "GRAPH_DUPLICATE_ID" | "GATE_UNKNOWN" | "GATE_GROUP_CYCLE" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "RESPONSE_TOO_LARGE" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "LEASE_STALE" | "CONTROLLER_BUSY" | "PAUSED" | "NOT_READY" | "SCOPE_VIOLATION" | "GATE_FAILED" | "REVIEW_REJECTED" | "BUDGET_EXHAUSTED" | "BUDGET_UNKNOWN" | "ATTEMPTS_EXHAUSTED" | "REVISION_CONFLICT" | "CANCELLED" | "NOT_FOUND" | "PATH_CONFLICT" | "STATE_VERSION_UNSUPPORTED" | "RUNTIME_UNAVAILABLE" | "REVIEW_PROTOCOL_INVALID" | "SANDBOX_UNAVAILABLE" | "GIT_FAILED" | "STORAGE_FAILED" | "DELIVERY_FAILED" | "INTERNAL" | undefined;
36
+ cause?: "gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | "runtime-missing" | "controller-busy" | "operator-pause" | "approval-required" | "not-ready" | undefined;
37
+ actor?: import("../projections/enums.ts").Actor | undefined;
38
+ action?: "none" | "wait" | "retry" | "review-plan" | "diagnose-failure" | "reset-attempts" | "raise-budget" | "replan-dependents" | "recovery-decision" | "user-decision" | "resume-queue" | "fix-environment" | "fix-access" | undefined;
39
+ failures?: ("gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead")[] | undefined;
40
+ operation?: string | undefined;
41
+ since?: string | undefined;
42
+ detail?: string;
43
+ paused: boolean;
44
+ reason?: import("../contracts/execution.ts").PauseReason;
45
+ };
46
+ attempts: import("../projections/attempt.ts").AttemptView[];
47
+ } | undefined;
48
+ budgets: {
49
+ onUnknown: "continue" | "stop";
50
+ budgets: {
51
+ reason?: string | undefined;
52
+ scope: import("../engine/budget.ts").BudgetScope;
53
+ state: "exceeded" | "undetermined" | "within";
54
+ limit: {
55
+ usd?: number;
56
+ timeMs?: number;
57
+ };
58
+ reportedUsd: number;
59
+ estimatedUsd: number;
60
+ unknownCalls: number;
61
+ unfinishedCalls: number;
62
+ abandonedCalls: number;
63
+ errorCalls: number;
64
+ uncoveredRuns: number;
65
+ durationMs: number;
66
+ remainingUsd: number | null;
67
+ remainingMs: number | null;
68
+ }[];
69
+ };
70
+ graphs: {
71
+ id: string;
72
+ digest: string;
73
+ source: {
74
+ connector: string;
75
+ ref: string;
76
+ revision: string;
77
+ };
78
+ approved: boolean;
79
+ }[];
80
+ works: ({
81
+ blockers: {
82
+ code: "NOT_READY" | "PAUSED" | "ATTEMPTS_EXHAUSTED" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "INVALID_INPUT";
83
+ message: string;
84
+ }[];
85
+ resultSha?: string | undefined;
86
+ liveness: "stalled" | "quiet";
87
+ activeRunId?: string | undefined;
88
+ id: string;
89
+ graphId: string;
90
+ status: "ready" | "failed" | "cancelled" | "draft" | "running" | "verifying" | "reviewing" | "integrating" | "done";
91
+ attempt: number;
92
+ } | {
93
+ blockers: {
94
+ code: "NOT_READY" | "PAUSED" | "ATTEMPTS_EXHAUSTED" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "INVALID_INPUT";
95
+ message: string;
96
+ }[];
97
+ resultSha?: string | undefined;
98
+ liveness?: undefined;
99
+ activeRunId?: string | undefined;
100
+ id: string;
101
+ graphId: string;
102
+ status: "ready" | "failed" | "cancelled" | "draft" | "running" | "verifying" | "reviewing" | "integrating" | "done";
103
+ attempt: number;
104
+ })[];
105
+ controller?: {
106
+ owner: string;
107
+ leaseUntil: number;
108
+ engineVersion?: string | undefined;
109
+ } | undefined;
110
+ stateVersion: 1;
111
+ control: {
112
+ paused: boolean;
113
+ pauseReason?: "runtime" | "operator" | "shutdown" | "base-check" | "reconfigure" | undefined;
114
+ pausedAt?: string | undefined;
115
+ pauseOperation?: string | undefined;
116
+ pauseFailures?: ("gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead")[] | undefined;
117
+ waits?: {
118
+ kind: "base-check" | "context-lock";
119
+ detail: string;
120
+ at: string;
121
+ operation?: string | undefined;
122
+ }[] | undefined;
123
+ appliedPolicy?: {
124
+ digest: string;
125
+ at: string;
126
+ by: string;
127
+ generation?: number | undefined;
128
+ } | undefined;
129
+ reconfigure?: {
130
+ operation: string;
131
+ digest: string;
132
+ requestedAt: string;
133
+ appliedAt?: string | undefined;
134
+ appliedBy?: string | undefined;
135
+ error?: string | undefined;
136
+ } | undefined;
137
+ };
138
+ } | {
139
+ detail?: {
140
+ at: string;
141
+ queue: {
142
+ liftedByRun: true;
143
+ code: "NOT_READY";
144
+ cause: "not-ready";
145
+ actor: "controller";
146
+ action: "wait";
147
+ operation?: string | undefined;
148
+ since?: string | undefined;
149
+ detail: string;
150
+ reason?: "runtime" | "operator" | "shutdown" | "base-check" | "reconfigure" | undefined;
151
+ paused: boolean;
152
+ } | {
153
+ code?: "INVALID_INPUT" | "UNSUPPORTED_COMMAND" | "UNSUPPORTED_VERSION" | "GRAPH_CYCLE" | "GRAPH_UNKNOWN_DEPENDENCY" | "GRAPH_DUPLICATE_ID" | "GATE_UNKNOWN" | "GATE_GROUP_CYCLE" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "RESPONSE_TOO_LARGE" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "LEASE_STALE" | "CONTROLLER_BUSY" | "PAUSED" | "NOT_READY" | "SCOPE_VIOLATION" | "GATE_FAILED" | "REVIEW_REJECTED" | "BUDGET_EXHAUSTED" | "BUDGET_UNKNOWN" | "ATTEMPTS_EXHAUSTED" | "REVISION_CONFLICT" | "CANCELLED" | "NOT_FOUND" | "PATH_CONFLICT" | "STATE_VERSION_UNSUPPORTED" | "RUNTIME_UNAVAILABLE" | "REVIEW_PROTOCOL_INVALID" | "SANDBOX_UNAVAILABLE" | "GIT_FAILED" | "STORAGE_FAILED" | "DELIVERY_FAILED" | "INTERNAL" | undefined;
154
+ cause?: "gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | "runtime-missing" | "controller-busy" | "operator-pause" | "approval-required" | "not-ready" | undefined;
155
+ actor?: import("../projections/enums.ts").Actor | undefined;
156
+ action?: "none" | "wait" | "retry" | "review-plan" | "diagnose-failure" | "reset-attempts" | "raise-budget" | "replan-dependents" | "recovery-decision" | "user-decision" | "resume-queue" | "fix-environment" | "fix-access" | undefined;
157
+ failures?: ("gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead")[] | undefined;
158
+ operation?: string | undefined;
159
+ since?: string | undefined;
160
+ detail?: string;
161
+ paused: boolean;
162
+ reason?: import("../contracts/execution.ts").PauseReason;
163
+ };
164
+ attempts: import("../projections/attempt.ts").AttemptView[];
165
+ } | undefined;
166
+ budgets?: undefined;
167
+ graphs: {
168
+ id: string;
169
+ digest: string;
170
+ source: {
171
+ connector: string;
172
+ ref: string;
173
+ revision: string;
174
+ };
175
+ approved: boolean;
176
+ }[];
177
+ works: ({
178
+ blockers: {
179
+ code: "NOT_READY" | "PAUSED" | "ATTEMPTS_EXHAUSTED" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "INVALID_INPUT";
180
+ message: string;
181
+ }[];
182
+ resultSha?: string | undefined;
183
+ liveness: "stalled" | "quiet";
184
+ activeRunId?: string | undefined;
185
+ id: string;
186
+ graphId: string;
187
+ status: "ready" | "failed" | "cancelled" | "draft" | "running" | "verifying" | "reviewing" | "integrating" | "done";
188
+ attempt: number;
189
+ } | {
190
+ blockers: {
191
+ code: "NOT_READY" | "PAUSED" | "ATTEMPTS_EXHAUSTED" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "INVALID_INPUT";
192
+ message: string;
193
+ }[];
194
+ resultSha?: string | undefined;
195
+ liveness?: undefined;
196
+ activeRunId?: string | undefined;
197
+ id: string;
198
+ graphId: string;
199
+ status: "ready" | "failed" | "cancelled" | "draft" | "running" | "verifying" | "reviewing" | "integrating" | "done";
200
+ attempt: number;
201
+ })[];
202
+ controller?: {
203
+ owner: string;
204
+ leaseUntil: number;
205
+ engineVersion?: string | undefined;
206
+ } | undefined;
207
+ stateVersion: 1;
208
+ control: {
209
+ paused: boolean;
210
+ pauseReason?: "runtime" | "operator" | "shutdown" | "base-check" | "reconfigure" | undefined;
211
+ pausedAt?: string | undefined;
212
+ pauseOperation?: string | undefined;
213
+ pauseFailures?: ("gate" | "unknown" | "review" | "cancelled" | "environment" | "timeout" | "provider-auth" | "stalled" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead")[] | undefined;
214
+ waits?: {
215
+ kind: "base-check" | "context-lock";
216
+ detail: string;
217
+ at: string;
218
+ operation?: string | undefined;
219
+ }[] | undefined;
220
+ appliedPolicy?: {
221
+ digest: string;
222
+ at: string;
223
+ by: string;
224
+ generation?: number | undefined;
225
+ } | undefined;
226
+ reconfigure?: {
227
+ operation: string;
228
+ digest: string;
229
+ requestedAt: string;
230
+ appliedAt?: string | undefined;
231
+ appliedBy?: string | undefined;
232
+ error?: string | undefined;
233
+ } | undefined;
234
+ };
235
+ };
@@ -0,0 +1,101 @@
1
+ import { STATE_VERSION } from "../contracts/index.js";
2
+ import { budgetOverview } from "../engine/budget.js";
3
+ import { nextRunControl } from "../explain/state.js";
4
+ import { CLIP_DIAGNOSTIC, attemptView, clipText, queuePause, queueStop, } from "../projections/index.js";
5
+ /**
6
+ * Состояние очереди, графов и поручений (`Harness.status`, `harness status`)
7
+ * над движком и политикой источника. С `detail` — ещё снимок наблюдателя:
8
+ * почему стоит выдача (`queueStop` и `queuePause`) и активные попытки
9
+ * (`attemptView`); без него ответ прежний. Только чтение, один `read`.
10
+ */
11
+ export function statusOf(source, graphId, options = {}) {
12
+ const { engine } = source;
13
+ return engine.read((v) => ({
14
+ stateVersion: STATE_VERSION,
15
+ control: v.control(),
16
+ ...(v.controller() ? { controller: v.controller() } : {}),
17
+ graphs: v
18
+ .graphs()
19
+ .filter((g) => !graphId || g.id === graphId)
20
+ .map((g) => ({
21
+ id: g.id,
22
+ digest: g.digest,
23
+ source: g.graph.source,
24
+ approved: g.approval?.digest === g.digest,
25
+ })),
26
+ works: v.works(graphId).map((w) => ({
27
+ id: w.id,
28
+ graphId: w.graphId,
29
+ status: w.status,
30
+ attempt: w.attempt,
31
+ ...(w.activeRunId ? { activeRunId: w.activeRunId } : {}),
32
+ ...((a) => a?.status === 'active' && a.liveness && a.liveness.state !== 'active'
33
+ ? { liveness: a.liveness.state }
34
+ : {})(w.activeRunId ? v.attempt(w.activeRunId) : undefined),
35
+ ...(w.resultSha ? { resultSha: w.resultSha } : {}),
36
+ blockers: engine.blockers(w, v),
37
+ })),
38
+ ...((budgets) => (budgets ? { budgets } : {}))(budgetOverview(engine.budgetContext(), v)),
39
+ ...(options.detail ? { detail: statusDetail(source, v, graphId) } : {}),
40
+ }));
41
+ }
42
+ function statusDetail(source, v, graphId) {
43
+ const { engine, policy } = source;
44
+ const now = engine.clock();
45
+ const control = v.control();
46
+ const works = v.works(graphId);
47
+ const attempts = v.works().flatMap((w) => v.attempts(w.id));
48
+ // Последний отказ классов паузы runtime — её подробность (как `queueStop`
49
+ // хоста по ошибкам планировщика): порядок — по времени завершения.
50
+ const failures = new Set(control.pauseFailures ?? []);
51
+ const errors = attempts
52
+ .filter((a) => a.status === 'failed' && a.failureKind && failures.has(a.failureKind))
53
+ .sort((a, b) => (a.finishedAt ?? '').localeCompare(b.finishedAt ?? ''))
54
+ .map((a, i) => ({ seq: i + 1, ...(a.error ? { message: a.error } : {}) }));
55
+ const stop = queueStop({
56
+ paused: control.paused,
57
+ ...(control.pauseReason ? { pauseReason: control.pauseReason } : {}),
58
+ errors,
59
+ });
60
+ const repositoryGates = (id) => policy.repositories.find((r) => r.id === id)?.gates.map((g) => g.id);
61
+ // Пауза, которую снимет следующий run, глазами explain: выдача не стоит,
62
+ // поручения ждут controller.
63
+ const queue = nextRunControl(source, v).lifted
64
+ ? {
65
+ paused: true,
66
+ ...(control.pauseReason ? { reason: control.pauseReason } : {}),
67
+ detail: 'Паузу снимет следующий harness run',
68
+ ...(control.pausedAt ? { since: control.pausedAt } : {}),
69
+ ...(control.pauseOperation ? { operation: control.pauseOperation } : {}),
70
+ liftedByRun: true,
71
+ code: 'NOT_READY',
72
+ cause: 'not-ready',
73
+ actor: 'controller',
74
+ action: 'wait',
75
+ }
76
+ : {
77
+ ...stop,
78
+ ...(stop.detail ? { detail: clipText(stop.detail, CLIP_DIAGNOSTIC) } : {}),
79
+ ...(control.paused && control.pausedAt ? { since: control.pausedAt } : {}),
80
+ ...(control.paused && control.pauseOperation ? { operation: control.pauseOperation } : {}),
81
+ ...(control.paused && control.pauseFailures?.length
82
+ ? { failures: [...control.pauseFailures] }
83
+ : {}),
84
+ ...(queuePause(control) ?? {}),
85
+ };
86
+ return {
87
+ at: new Date(now).toISOString(),
88
+ queue,
89
+ attempts: works
90
+ .map((w) => (w.activeRunId ? v.attempt(w.activeRunId) : undefined))
91
+ .filter((a) => a?.status === 'active')
92
+ .map((a) => {
93
+ const gates = repositoryGates(a.repositoryId);
94
+ return attemptView(a, {
95
+ now,
96
+ leaseMs: policy.leaseMs,
97
+ ...(gates ? { repositoryGates: gates } : {}),
98
+ });
99
+ }),
100
+ };
101
+ }