mandrel 2.119.0 → 2.121.0

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 (47) hide show
  1. package/.agents/agents/acceptance-critic.md +4 -0
  2. package/.agents/agents/story-worker.md +1 -1
  3. package/.agents/docs/agentrc-reference.json +1 -0
  4. package/.agents/docs/configuration.md +18 -3
  5. package/.agents/schemas/acceptance-eval-verdict.schema.json +6 -1
  6. package/.agents/schemas/agentrc.schema.json +11 -2
  7. package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
  8. package/.agents/schemas/story-deliver-terminal.schema.json +1 -0
  9. package/.agents/scripts/acceptance-eval.js +125 -13
  10. package/.agents/scripts/evidence-gate.js +15 -2
  11. package/.agents/scripts/lib/baselines/crap-preview-scan.js +1 -0
  12. package/.agents/scripts/lib/baselines/git-base.js +43 -0
  13. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +29 -5
  14. package/.agents/scripts/lib/baselines/kinds/crap.js +7 -1
  15. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +81 -52
  16. package/.agents/scripts/lib/close-validation/projections/advisories.js +1 -0
  17. package/.agents/scripts/lib/close-validation/projections/crap.js +3 -0
  18. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  19. package/.agents/scripts/lib/config/gates/crap.schema.js +7 -0
  20. package/.agents/scripts/lib/config/quality.js +13 -6
  21. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  23. package/.agents/scripts/lib/observability/handoff-telemetry.js +1 -0
  24. package/.agents/scripts/lib/orchestrate/inventory.js +15 -0
  25. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +65 -6
  26. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +34 -2
  27. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +7 -2
  28. package/.agents/scripts/lib/orchestration/handoff-changed-tests.js +67 -0
  29. package/.agents/scripts/lib/orchestration/handoff-gates.js +2 -0
  30. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +25 -10
  31. package/.agents/scripts/lib/orchestration/merge-block-class.js +1 -0
  32. package/.agents/scripts/lib/orchestration/merge-queue.js +155 -14
  33. package/.agents/scripts/lib/orchestration/preflight-lanes.js +2 -0
  34. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +131 -18
  35. package/.agents/scripts/lib/orchestration/story-handoff.js +24 -1
  36. package/.agents/scripts/lib/orchestration/ticket-validator.js +35 -0
  37. package/.agents/scripts/lib/orchestration/verify-credit.js +144 -0
  38. package/.agents/scripts/lib/validation-evidence.js +27 -0
  39. package/.agents/workflows/helpers/acceptance-self-eval.md +9 -1
  40. package/.agents/workflows/helpers/deliver-digest.md +7 -8
  41. package/.agents/workflows/helpers/deliver-reference.md +17 -0
  42. package/.agents/workflows/helpers/deliver-story-reference.md +1 -1
  43. package/.agents/workflows/helpers/plan-reference.md +3 -1
  44. package/docs/CHANGELOG.md +23 -0
  45. package/lib/cli/doctor-checks/suite-ownership.js +42 -0
  46. package/lib/cli/registry.js +6 -10
  47. package/package.json +1 -1
@@ -30,6 +30,7 @@ const HANDOFF_CAUSES = Object.freeze(
30
30
  'host-admission',
31
31
  'suite-timeout',
32
32
  'red-suite',
33
+ 'changed-tests',
33
34
  'capture-over-budget',
34
35
  'no-credit-signal',
35
36
  'seat-refused',
@@ -310,6 +310,21 @@ function orchestrateConfig(config) {
310
310
  const runVetoCommand = ({ cmd, args }, cwd) =>
311
311
  spawnCapture(cmd, args, { cwd }).status !== 0;
312
312
 
313
+ /** Whether `delivery.orchestrate.releaseVeto` holds a PR carrying `labels`. */
314
+ export function releaseVetoHolds({
315
+ config,
316
+ labels,
317
+ cwd,
318
+ runVeto = runVetoCommand,
319
+ }) {
320
+ const { releaseVeto } = orchestrateConfig(config);
321
+ return Boolean(
322
+ releaseVeto &&
323
+ labels.includes(releaseVeto.prLabel) &&
324
+ runVeto(releaseVeto, cwd),
325
+ );
326
+ }
327
+
313
328
  /**
314
329
  * One sweep: read, resolve conflicts and the veto, classify, and with a
315
330
  * run id append the sweep and fill `changes[]`.
@@ -9,6 +9,7 @@ import { createHash } from 'node:crypto';
9
9
  import { readFileSync } from 'node:fs';
10
10
 
11
11
  import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
12
+ import { normalizeVerifyCommand } from './verify-credit.js';
12
13
 
13
14
  const EPIC_SIGNALS_BASENAME = 'signals.ndjson';
14
15
 
@@ -55,11 +56,52 @@ function partitionCriteria(criteria) {
55
56
  return { metCount, notMet };
56
57
  }
57
58
 
59
+ /**
60
+ * Fold the gate's own verify runs into the verdict: a criterion citing a
61
+ * failed run without a `waiver` is scored `unmet`, whatever it self-reported.
62
+ *
63
+ * @param {{ criteria?: Array<object> }} verdict
64
+ * @param {Array<{ command: string, exitCode: number|null, outcome: string, deadPaths?: string[] }>} [verifyRuns]
65
+ * @returns {{ criteria: Array<object>, verifyRuns: Array<object> }}
66
+ */
67
+ export function scoreVerifyRuns(verdict, verifyRuns = []) {
68
+ const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
69
+ const cites = (c) =>
70
+ (c?.verifyEvidence ?? []).map((item) => ({
71
+ command: normalizeVerifyCommand(item?.command),
72
+ waived: typeof item?.waiver === 'string' && item.waiver.length > 0,
73
+ }));
74
+ const runs = verifyRuns.map((run) => ({
75
+ ...run,
76
+ waived: criteria.some((c) =>
77
+ cites(c).some((i) => i.waived && i.command === run.command),
78
+ ),
79
+ }));
80
+ const failed = new Map(
81
+ runs.filter((r) => r.outcome !== 'pass').map((r) => [r.command, r]),
82
+ );
83
+ const scored = criteria.map((c) => {
84
+ const hit = cites(c).find((i) => !i.waived && failed.has(i.command));
85
+ if (!hit) return c;
86
+ const run = failed.get(hit.command);
87
+ const why = run.deadPaths?.length
88
+ ? `selects no test file at ${run.deadPaths.join(', ')}`
89
+ : `exited ${run.exitCode ?? 'without a code (timeout or spawn failure)'}`;
90
+ return {
91
+ ...c,
92
+ verdict: 'unmet',
93
+ evidence: `gate run of \`${run.command}\` ${why}; ${c.evidence ?? ''}`,
94
+ };
95
+ });
96
+ return { criteria: scored, verifyRuns: runs };
97
+ }
98
+
58
99
  /**
59
100
  * @param {object} args
60
101
  * @param {{ criteria?: Array<object> }} args.verdict Its own `round` is ignored.
61
102
  * @param {number} args.maxRounds
62
103
  * @param {number} [args.round] From `resolveAcceptanceEvalRound`.
104
+ * @param {Array<object>} [args.verifyRuns] The gate's own scoped runs.
63
105
  * @returns {{
64
106
  * decision: 'proceed' | 'redraft' | 'block',
65
107
  * round: number,
@@ -70,10 +112,17 @@ function partitionCriteria(criteria) {
70
112
  * capReached: boolean,
71
113
  * }}
72
114
  */
73
- export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
115
+ export function decideAcceptanceEval({
116
+ verdict,
117
+ maxRounds,
118
+ round: roundIn,
119
+ verifyRuns = [],
120
+ }) {
74
121
  const cap = effectiveCap(maxRounds);
75
122
  const round = Number.isInteger(roundIn) && roundIn >= 1 ? roundIn : 1;
76
- const { metCount, notMet } = partitionCriteria(verdict?.criteria);
123
+ const { metCount, notMet } = partitionCriteria(
124
+ scoreVerifyRuns(verdict, verifyRuns).criteria,
125
+ );
77
126
  const totalCriteria = metCount + notMet.length;
78
127
  const allMet = notMet.length === 0;
79
128
  const capReached = round >= cap;
@@ -205,14 +254,24 @@ function readPriorAcceptanceEvalRecords({
205
254
  return records;
206
255
  }
207
256
 
257
+ /** No gate inputs hashes the verdict alone, keeping recorded fingerprints. */
258
+ function withGateInputs(canonical, { verifyRuns = [], headSha = null } = {}) {
259
+ const runs = verifyRuns.map((r) => [r.command, r.outcome]);
260
+ return runs.length > 0 || headSha
261
+ ? { canonical, runs, head: headSha }
262
+ : canonical;
263
+ }
264
+
208
265
  /**
209
- * Hashes only what the decision depends on, so an unchanged evaluation
210
- * fingerprints the same and real rework does not.
266
+ * Hashes only what the decision depends on — the verdict, the gate's real
267
+ * verify outcomes and HEAD — so an unchanged evaluation fingerprints the same
268
+ * and real rework does not.
211
269
  *
212
270
  * @param {{ criteria?: Array<object> }} verdict
271
+ * @param {{ verifyRuns?: Array<{ command: string, outcome: string }>, headSha?: string|null }} [gate]
213
272
  * @returns {string}
214
273
  */
215
- export function computeVerdictFingerprint(verdict) {
274
+ export function computeVerdictFingerprint(verdict, gate) {
216
275
  const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
217
276
  const canonical = criteria.map((c) => [
218
277
  Number.isInteger(c?.index) ? c.index : null,
@@ -221,7 +280,7 @@ export function computeVerdictFingerprint(verdict) {
221
280
  typeof c?.evidence === 'string' ? c.evidence : '',
222
281
  ]);
223
282
  return createHash('sha256')
224
- .update(JSON.stringify(canonical))
283
+ .update(JSON.stringify(withGateInputs(canonical, gate)))
225
284
  .digest('hex')
226
285
  .slice(0, 16);
227
286
  }
@@ -7,8 +7,12 @@
7
7
 
8
8
  import { decodeEnvelope } from '../../../baselines/codec.js';
9
9
  import { EXIT_CONFIG } from '../../../baselines/exit-codes.js';
10
- import { readBaseFromGit } from '../../../baselines/git-base.js';
10
+ import {
11
+ readBaseFromGit,
12
+ readRenamesFromGit,
13
+ } from '../../../baselines/git-base.js';
11
14
  import { getKindModule } from '../../../baselines/kernel.js';
15
+ import { canonicalizeBaselinePath } from '../../../baselines/path-canon.js';
12
16
  import { resolveScope } from '../../../baselines/scope.js';
13
17
  import { Logger } from '../../../Logger.js';
14
18
  import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
@@ -71,6 +75,27 @@ function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
71
75
  }
72
76
  }
73
77
 
78
+ /** Git renames since the base ref, keyed by canonical baseline path. */
79
+ function canonicalRenames(ref, cwd) {
80
+ const out = new Map();
81
+ for (const [to, from] of readRenamesFromGit(ref, { cwd })) {
82
+ out.set(canonicalizeBaselinePath(to), canonicalizeBaselinePath(from));
83
+ }
84
+ return out;
85
+ }
86
+
87
+ /**
88
+ * The compare's third argument: renames for every kind, and the coverage
89
+ * `*` floor as the minimum a new file must meet.
90
+ */
91
+ function compareOptionsFor(kind, gateBlock, scope, cwd) {
92
+ const floor = gateBlock?.floors?.['*'];
93
+ return {
94
+ renames: canonicalRenames(scope.ref, cwd),
95
+ newFileMinimum: kind === 'coverage' && floor ? floor : null,
96
+ };
97
+ }
98
+
74
99
  export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
75
100
  if (scope.mode !== 'diff' || !scope.ref) return emptyCompareResult(null);
76
101
  const basePayload = readBaseBaselinePayload(scope, kind, gateBlock, cwd);
@@ -79,7 +104,13 @@ export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
79
104
  if (typeof kindModule.compare !== 'function') {
80
105
  return emptyCompareResult(scope.ref);
81
106
  }
82
- return { baseRef: scope.ref, baseRead: true, basePayload, kindModule };
107
+ return {
108
+ baseRef: scope.ref,
109
+ baseRead: true,
110
+ basePayload,
111
+ kindModule,
112
+ compareOptions: compareOptionsFor(kind, gateBlock, scope, cwd),
113
+ };
83
114
  }
84
115
 
85
116
  /**
@@ -119,6 +150,7 @@ export function runCompareStage(headBaseline, cmp) {
119
150
  const result = cmp.kindModule.compare(
120
151
  { rows: headBaseline.rows },
121
152
  { rows: baseRows },
153
+ cmp.compareOptions,
122
154
  );
123
155
  return {
124
156
  regressions: result?.regressions ?? [],
@@ -43,7 +43,7 @@ function formatRemedyLine(g) {
43
43
  const fmt = (n) => String(Number(n.toFixed(2)));
44
44
 
45
45
  /** `<field> <base> → <head>` per numeric field that moved; `(new)` without a base. */
46
- function formatRegressionLine({ key, head, base }) {
46
+ function formatRegressionLine({ key, head, base, renamedFrom, newFile }) {
47
47
  const numeric = Object.entries(head ?? {}).filter(
48
48
  ([, v]) => typeof v === 'number',
49
49
  );
@@ -54,7 +54,12 @@ function formatRegressionLine({ key, head, base }) {
54
54
  const moved = numeric
55
55
  .filter(([f, v]) => typeof base[f] === 'number' && base[f] !== v)
56
56
  .map(([f, v]) => `${f} ${fmt(base[f])} → ${fmt(v)}`);
57
- return ` · ${key}: ${moved.join(', ')}`;
57
+ return ` · ${regressionLabel(key, renamedFrom, newFile)}: ${moved.join(', ')}`;
58
+ }
59
+
60
+ function regressionLabel(key, renamedFrom, newFile) {
61
+ if (renamedFrom) return `${key} (renamed from ${renamedFrom})`;
62
+ return newFile ? `${key} (new, under the minimum)` : key;
58
63
  }
59
64
 
60
65
  function formatRegressionLines(g) {
@@ -0,0 +1,67 @@
1
+ /**
2
+ * handoff-changed-tests.js — the `ci` posture's changed-tests guard:
3
+ * `project.commands.testChanged` run before the deferral settles, with no
4
+ * lock and no credit.
5
+ */
6
+
7
+ import { resolveTestChangedCommand } from '../close-validation/test-delta.js';
8
+ import { TIMEOUT_EXIT_CODE } from '../process-group.js';
9
+ import { isOverBudgetExit } from './handoff-gates.js';
10
+
11
+ /** Why a guard exit other than 0 or 76 stops the handoff. */
12
+ function guardFailure(raw, status) {
13
+ return status === TIMEOUT_EXIT_CODE
14
+ ? `changed-tests guard timed out (exit ${status}) — usually host contention; re-run the handoff`
15
+ : `changed-tests guard \`${raw}\` failed (exit ${status}) — fix the failing tests, commit, re-run`;
16
+ }
17
+
18
+ /** A guard exit as `{ stop }`, else the `note` the deferral detail carries. */
19
+ function settleGuard(ctx, name, { status, raw, extra }) {
20
+ if (status === 0) {
21
+ ctx.state.changedTestsHead = ctx.head;
22
+ return { note: '; changed-tests guard passed', extra };
23
+ }
24
+ if (isOverBudgetExit(status)) {
25
+ return {
26
+ note: `; changed-tests guard skipped (over budget, exit ${status})`,
27
+ extra,
28
+ };
29
+ }
30
+ const detail = guardFailure(raw, status);
31
+ return {
32
+ stop: {
33
+ name,
34
+ outcome: 'failed',
35
+ detail,
36
+ stop: 'fix-required',
37
+ cause: 'changed-tests',
38
+ ...extra,
39
+ },
40
+ };
41
+ }
42
+
43
+ /**
44
+ * Run `testChanged` unless unset or already passed at HEAD.
45
+ *
46
+ * @param {{ config: object, head: string, state: object, depositor: string }} ctx
47
+ * @param {string} name
48
+ * @param {{ run: (cmd: object) => Promise<{ status: number, evidencePath: string }>, signal: AbortSignal }} guard
49
+ * @returns {Promise<{ stop?: object, note?: string, extra?: object }>}
50
+ */
51
+ export async function changedTestsGuard(ctx, name, guard) {
52
+ const testChanged = resolveTestChangedCommand(ctx.config);
53
+ if (testChanged.disabled) return { note: '' };
54
+ if (ctx.state.changedTestsHead === ctx.head) {
55
+ return {
56
+ note: `; changed-tests guard already passed at ${ctx.head.slice(0, 12)}`,
57
+ };
58
+ }
59
+ const { status, evidencePath } = await guard.run(testChanged);
60
+ const extra = { evidencePath, depositor: ctx.depositor };
61
+ if (!guard.signal.aborted) {
62
+ return settleGuard(ctx, name, { status, raw: testChanged.raw, extra });
63
+ }
64
+ const detail =
65
+ 'aborted: the held review found a CRITICAL mid-guard; no deferral';
66
+ return { stop: { name, outcome: 'aborted', detail, ...extra } };
67
+ }
@@ -22,6 +22,7 @@ import {
22
22
  } from '../coverage-deferral.js';
23
23
  import { quoteFailureRows } from '../failure-rows.js';
24
24
  import {
25
+ assertCleanTree,
25
26
  hashCommandConfig,
26
27
  recordPass,
27
28
  treeFingerprint,
@@ -153,6 +154,7 @@ export function recordPreflightCredit(ctx, check) {
153
154
  /** Re-key one credit onto the seated HEAD; best-effort, like close's rerun. */
154
155
  export function carryCredit(ctx, gateName, credit) {
155
156
  try {
157
+ assertCleanTree(ctx.cwd, ctx.git);
156
158
  recordPass(
157
159
  {
158
160
  storyId: ctx.storyId,
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * handoff-suite-of-record.js — the credited-run step under
3
- * `coverage.suiteOfRecord: "ci"`, decided from config before any lock or spawn.
3
+ * `coverage.suiteOfRecord: "ci"`, decided from config before any lock or spawn
4
+ * but the changed-tests guard.
4
5
  */
5
6
 
6
7
  import { suiteOfRecord } from '../close-validation/gates.js';
@@ -8,10 +9,28 @@ import {
8
9
  COVERAGE_DEFERRED_REASONS,
9
10
  deferCoverage,
10
11
  } from '../coverage-deferral.js';
12
+ import { changedTestsGuard } from './handoff-changed-tests.js';
11
13
 
12
14
  const UNDECLARED_DETAIL =
13
15
  'delivery.quality.gates.coverage.suiteOfRecord is "ci" but delivery.quality.gates.coverage.ciRatchetCheck is unset — name the CI check that runs coverage-ratchet.js, or set suiteOfRecord to "local"';
14
16
 
17
+ /**
18
+ * The deferred step, once the changed-tests guard did not stop the run.
19
+ *
20
+ * @param {object} ctx @param {string} name @param {string} ciRatchetCheck
21
+ * @param {{ note: string, extra?: object }} checked
22
+ */
23
+ function deferred(ctx, name, ciRatchetCheck, checked) {
24
+ deferCoverage(ctx.state, ctx.head, COVERAGE_DEFERRED_REASONS.suiteOfRecordCi);
25
+ return {
26
+ name,
27
+ outcome: 'deferred',
28
+ detail: `coverage deferred to CI (suiteOfRecord: ci, ratchet check "${ciRatchetCheck}") — no capture spawned and no credit was deposited${checked.note}`,
29
+ depositor: ctx.depositor,
30
+ ...checked.extra,
31
+ };
32
+ }
33
+
15
34
  /**
16
35
  * The capture depositor's step under the `ci` posture: deferred to CI, or
17
36
  * `blocked` when no `ciRatchetCheck` would take the ratchet. `null` when the
@@ -19,9 +38,10 @@ const UNDECLARED_DETAIL =
19
38
  *
20
39
  * @param {{ config: object, depositor: string, head: string, state: object }} ctx
21
40
  * @param {string} name
22
- * @returns {object|null}
41
+ * @param {{ run: Function, signal: AbortSignal }} guard runs `testChanged`.
42
+ * @returns {Promise<object|null>}
23
43
  */
24
- export function settleSuiteOfRecord(ctx, name) {
44
+ export async function settleSuiteOfRecord(ctx, name, guard) {
25
45
  const { ci, ciRatchetCheck } = suiteOfRecord(ctx.config);
26
46
  if (!ci || ctx.depositor !== 'coverage-capture') return null;
27
47
  const extra = { depositor: ctx.depositor };
@@ -35,11 +55,6 @@ export function settleSuiteOfRecord(ctx, name) {
35
55
  ...extra,
36
56
  };
37
57
  }
38
- deferCoverage(ctx.state, ctx.head, COVERAGE_DEFERRED_REASONS.suiteOfRecordCi);
39
- return {
40
- name,
41
- outcome: 'deferred',
42
- detail: `coverage deferred to CI (suiteOfRecord: ci, ratchet check "${ciRatchetCheck}") — nothing spawned and no credit was deposited`,
43
- ...extra,
44
- };
58
+ const checked = await changedTestsGuard(ctx, name, guard);
59
+ return checked.stop ?? deferred(ctx, name, ciRatchetCheck, checked);
45
60
  }
@@ -29,6 +29,7 @@ export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
29
29
  ADVISORY_GATE_RED_CLASS,
30
30
  ADVISORY_GATE_INCONCLUSIVE_CLASS,
31
31
  'merge-queue-rest-unsupported',
32
+ 'queue-ejected',
32
33
  ]);
33
34
 
34
35
  const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);
@@ -10,7 +10,7 @@ import {
10
10
  describeGhFailure,
11
11
  prTransportOf,
12
12
  } from '../gh-exec.js';
13
- import { readBranchRules } from '../gh-pr-rest.js';
13
+ import { parseApiJson, readBranchRules } from '../gh-pr-rest.js';
14
14
 
15
15
  /** Bound on each merge-queue GraphQL call, so a wedged `gh` cannot stall close. */
16
16
  const MERGE_QUEUE_GH_TIMEOUT_MS = 30_000;
@@ -21,6 +21,20 @@ const MERGE_QUEUE_STATE_QUERY =
21
21
  const DEQUEUE_MUTATION =
22
22
  'mutation($id: ID!) { dequeuePullRequest(input: { id: $id }) { mergeQueueEntry { id } } }';
23
23
 
24
+ const EJECTION_QUERY =
25
+ 'query($id: ID!) { node(id: $id) { ... on PullRequest { baseRefName labels(first: 20) { nodes { name } } ' +
26
+ 'timelineItems(last: 1, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT]) { nodes { __typename ' +
27
+ '... on RemovedFromMergeQueueEvent { createdAt reason beforeCommit { oid } } } } ' +
28
+ 'commits(last: 1) { nodes { commit { committedDate } } } } } }';
29
+
30
+ const QUEUE_RUNS = 'repos/{owner}/{repo}/actions/runs?event=merge_group';
31
+
32
+ /** Inherited ejections re-armed per head; the next one counts as own. */
33
+ const MAX_INHERITED_REARMS = 3;
34
+
35
+ /** Block class: the merge queue ejected the PR on its own failure. */
36
+ export const QUEUE_EJECTED_BLOCK_CLASS = 'queue-ejected';
37
+
24
38
  /** `gh` stderr when the base requires a merge queue and the arm spelling is wrong. */
25
39
  export const MERGE_QUEUE_REFUSAL = /when merge queue enabled/i;
26
40
 
@@ -70,6 +84,25 @@ export function parseGraphqlData(result) {
70
84
  return parsed?.data ?? null;
71
85
  }
72
86
 
87
+ async function resolvePrNodeId(facade, prNodeId, prRef) {
88
+ if (prNodeId) return prNodeId;
89
+ const view = await facade.pr.view(String(prRef), ['id']);
90
+ if (typeof view?.id === 'string' && view.id) return view.id;
91
+ throw new Error('PR node id unavailable');
92
+ }
93
+
94
+ async function queryPrNode(facade, query, id, timeoutMs) {
95
+ const data = parseGraphqlData(
96
+ await facade.api({
97
+ method: 'POST',
98
+ endpoint: 'graphql',
99
+ body: { query, variables: { id } },
100
+ execOpts: { timeoutMs },
101
+ }),
102
+ );
103
+ return data?.node;
104
+ }
105
+
73
106
  /**
74
107
  * Whether the PR's base requires a merge queue, and whether the PR sits in
75
108
  * it now. Keyed on the PR node, so it needs no owner/repo. Never throws: any
@@ -99,20 +132,13 @@ export async function readMergeQueueState({
99
132
  timeoutMs,
100
133
  });
101
134
  }
102
- if (!id) {
103
- const view = await facade.pr.view(String(prRef ?? prNumber), ['id']);
104
- id = typeof view?.id === 'string' && view.id ? view.id : null;
105
- }
106
- if (!id) throw new Error('PR node id unavailable');
107
- const data = parseGraphqlData(
108
- await facade.api({
109
- method: 'POST',
110
- endpoint: 'graphql',
111
- body: { query: MERGE_QUEUE_STATE_QUERY, variables: { id } },
112
- execOpts: { timeoutMs },
113
- }),
135
+ id = await resolvePrNodeId(facade, id, prRef ?? prNumber);
136
+ const node = await queryPrNode(
137
+ facade,
138
+ MERGE_QUEUE_STATE_QUERY,
139
+ id,
140
+ timeoutMs,
114
141
  );
115
- const node = data?.node;
116
142
  if (typeof node?.isMergeQueueEnabled !== 'boolean') {
117
143
  throw new Error('merge-queue fields absent from the GraphQL response');
118
144
  }
@@ -131,6 +157,121 @@ export async function readMergeQueueState({
131
157
  }
132
158
  }
133
159
 
160
+ const RED_RUN = new Set(['failure', 'cancelled']);
161
+ const byNewest = (a, b) =>
162
+ String(b.created_at ?? '').localeCompare(String(a.created_at ?? ''));
163
+
164
+ /** The last queue event removed this head without merging it. */
165
+ function ejectedHead(pr, headSha) {
166
+ const event = pr?.timelineItems?.nodes?.at(-1);
167
+ if (event?.__typename !== 'RemovedFromMergeQueueEvent') return false;
168
+ if (/merged/i.test(event.reason ?? '')) return false;
169
+ const removed = event.beforeCommit?.oid;
170
+ if (removed) return removed === headSha;
171
+ const pushedAt = pr.commits?.nodes?.[0]?.commit?.committedDate;
172
+ return !(Date.parse(event.createdAt) < Date.parse(pushedAt));
173
+ }
174
+
175
+ /** The newest entry's completed run, a red one first. */
176
+ function ejectingRunOf(runs) {
177
+ const latest = runs[0]?.head_sha;
178
+ const done = runs.filter(
179
+ (r) => r.head_sha === latest && r.status === 'completed',
180
+ );
181
+ return (
182
+ done.find((r) => r.conclusion === 'failure') ??
183
+ done.find((r) => r.conclusion === 'cancelled') ??
184
+ done[0] ??
185
+ null
186
+ );
187
+ }
188
+
189
+ /** First rule wins: inherited (capped), own, unknown. */
190
+ function classifyEjection({ ejecting, parentRuns, entries }) {
191
+ const inherited =
192
+ ejecting.conclusion === 'cancelled' ||
193
+ parentRuns.some((r) => RED_RUN.has(r.conclusion));
194
+ if (inherited) return entries > MAX_INHERITED_REARMS ? 'own' : 'inherited';
195
+ return ejecting.conclusion === 'failure' ? 'own' : 'unknown';
196
+ }
197
+
198
+ /**
199
+ * Why the merge queue ejected `headSha`, read from the `merge_group` run on
200
+ * its `gh-readonly-queue/<base>/pr-<n>-<parentSha>` ref and the run of the
201
+ * entry it was built on. GraphQL only; never throws (a failed read is
202
+ * `unknown`). `verdict: null` means the last queue event is no ejection.
203
+ *
204
+ * @returns {Promise<{ verdict: 'inherited'|'own'|'unknown'|null,
205
+ * labels: string[], run?: object, failedJobs?: string[], detail?: string }>}
206
+ */
207
+ export async function readQueueEjection({
208
+ prNodeId,
209
+ prNumber,
210
+ headSha,
211
+ gh,
212
+ timeoutMs = MERGE_QUEUE_GH_TIMEOUT_MS,
213
+ }) {
214
+ const facade = gh ?? defaultGh;
215
+ const get = async (endpoint) =>
216
+ parseApiJson(
217
+ await facade.api({ method: 'GET', endpoint, execOpts: { timeoutMs } }),
218
+ );
219
+ let labels = [];
220
+ try {
221
+ const id = await resolvePrNodeId(facade, prNodeId, prNumber);
222
+ const pr = await queryPrNode(facade, EJECTION_QUERY, id, timeoutMs);
223
+ labels = (pr?.labels?.nodes ?? []).map((l) => l.name);
224
+ if (!ejectedHead(pr, headSha)) return { verdict: null, labels };
225
+ const prefix = `gh-readonly-queue/${pr.baseRefName}/pr-${prNumber}-`;
226
+ const pushedAt = Date.parse(pr.commits?.nodes?.[0]?.commit?.committedDate);
227
+ // shortcut: the newest 100 queue runs; page further if a queue outgrows it.
228
+ const runs = (
229
+ (await get(`${QUEUE_RUNS}&per_page=100`))?.workflow_runs ?? []
230
+ )
231
+ .filter((r) => String(r.head_branch ?? '').startsWith(prefix))
232
+ .filter((r) => !(Date.parse(r.created_at) < pushedAt))
233
+ .sort(byNewest);
234
+ const ejecting = ejectingRunOf(runs);
235
+ if (!ejecting) {
236
+ return { verdict: 'unknown', labels, detail: 'no completed queue run' };
237
+ }
238
+ const parentSha = ejecting.head_branch.slice(prefix.length);
239
+ const parentRuns = (
240
+ (await get(`${QUEUE_RUNS}&head_sha=${parentSha}`))?.workflow_runs ?? []
241
+ ).filter((r) => r.head_sha === parentSha);
242
+ const verdict = classifyEjection({
243
+ ejecting,
244
+ parentRuns,
245
+ entries: new Set(runs.map((r) => r.head_sha)).size,
246
+ });
247
+ const run = {
248
+ id: ejecting.id,
249
+ name: ejecting.name ?? null,
250
+ url: ejecting.html_url ?? null,
251
+ conclusion: ejecting.conclusion,
252
+ };
253
+ const failedJobs =
254
+ verdict === 'own' ? await readFailedJobs(get, ejecting.id) : [];
255
+ return { verdict, labels, run, failedJobs };
256
+ } catch (err) {
257
+ return { verdict: 'unknown', labels, detail: describeGhFailure(err) };
258
+ }
259
+ }
260
+
261
+ /** Failed job names of a run; `[]` when unreadable. */
262
+ async function readFailedJobs(get, runId) {
263
+ try {
264
+ const body = await get(
265
+ `repos/{owner}/{repo}/actions/runs/${runId}/jobs?filter=latest&per_page=100`,
266
+ );
267
+ return (body?.jobs ?? [])
268
+ .filter((j) => j.conclusion === 'failure')
269
+ .map((j) => j.name);
270
+ } catch {
271
+ return [];
272
+ }
273
+ }
274
+
134
275
  /**
135
276
  * Take an enqueued PR out of the merge queue. `--disable-auto` cannot: GitHub
136
277
  * clears the auto-merge request on enqueue, so it reads as never armed.
@@ -12,6 +12,7 @@ import {
12
12
  SUITE_RESERVATION_ENV,
13
13
  } from '../full-suite-lock.js';
14
14
  import {
15
+ assertCleanTree,
15
16
  hashCommandConfig,
16
17
  recordPass,
17
18
  shouldSkip,
@@ -190,6 +191,7 @@ function reconcileDeposit(ctx, check) {
190
191
  const opts = { cwd: ctx.evidenceCwd, standalone: true };
191
192
  const key = { storyId: ctx.storyId, gateName: check.key, configHash };
192
193
  try {
194
+ assertCleanTree(ctx.cwd, ctx.git);
193
195
  if (shouldSkip({ ...key, currentSha: ctx.head }, opts).skip) return;
194
196
  recordPass(
195
197
  {