mandrel 2.117.0 → 2.119.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 (38) hide show
  1. package/.agents/docs/agentrc-reference.json +2 -1
  2. package/.agents/docs/configuration.md +14 -5
  3. package/.agents/schemas/agentrc.schema.json +25 -2
  4. package/.agents/schemas/story-deliver-terminal.schema.json +15 -1
  5. package/.agents/scripts/lib/baselines/coverage-updater-cli.js +2 -6
  6. package/.agents/scripts/lib/baselines/crap-preview-coverage.js +17 -0
  7. package/.agents/scripts/lib/baselines/crap-preview-scan.js +11 -6
  8. package/.agents/scripts/lib/baselines/preview-gates.js +2 -0
  9. package/.agents/scripts/lib/baselines/refresh-service.js +23 -12
  10. package/.agents/scripts/lib/baselines/seat-missing.js +2 -9
  11. package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +152 -0
  12. package/.agents/scripts/lib/close-validation/ci-deferral.js +23 -5
  13. package/.agents/scripts/lib/close-validation/gates.js +8 -2
  14. package/.agents/scripts/lib/close-validation/runner.js +8 -10
  15. package/.agents/scripts/lib/config-settings-schema-delivery.js +22 -2
  16. package/.agents/scripts/lib/coverage-baseline.js +20 -9
  17. package/.agents/scripts/lib/coverage-deferral.js +17 -0
  18. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  19. package/.agents/scripts/lib/observability/story-outcome.js +5 -4
  20. package/.agents/scripts/lib/orchestration/handoff-rescore.js +95 -25
  21. package/.agents/scripts/lib/orchestration/merge-block-class.js +12 -1
  22. package/.agents/scripts/lib/orchestration/merge-poll.js +9 -0
  23. package/.agents/scripts/lib/orchestration/merge-queue.js +14 -7
  24. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +2 -25
  25. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +8 -1
  26. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +26 -7
  27. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +50 -8
  28. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +3 -2
  29. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +9 -3
  30. package/.agents/scripts/lib/orchestration/single-story-close/result.js +9 -6
  31. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +1 -0
  32. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +158 -71
  33. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +4 -0
  34. package/.agents/scripts/lib/orchestration/story-handoff.js +100 -25
  35. package/.agents/scripts/quality-preview.js +57 -8
  36. package/.agents/workflows/helpers/deliver-reference.md +10 -1
  37. package/docs/CHANGELOG.md +17 -0
  38. package/package.json +1 -1
@@ -70,10 +70,10 @@ function resolveMandrelVersion(root = PROJECT_ROOT) {
70
70
  return typeof pkg?.version === 'string' ? pkg.version : null;
71
71
  }
72
72
 
73
- /** @param {Record<string, string>|null|undefined} gates */
74
- function failedGateNames(gates) {
73
+ /** @param {Record<string, string>|null|undefined} gates @param {string} wanted */
74
+ function gateNamesWith(gates, wanted) {
75
75
  return Object.entries(gates ?? {})
76
- .filter(([, outcome]) => outcome === 'failed')
76
+ .filter(([, outcome]) => outcome === wanted)
77
77
  .map(([name]) => name)
78
78
  .sort();
79
79
  }
@@ -130,7 +130,8 @@ function buildAttempt({
130
130
  phase: envelope.phase ?? null,
131
131
  cause: retryCauseForTerminal(envelope),
132
132
  blockClass: envelope.blocked?.blockClass ?? null,
133
- failedGates: failedGateNames(envelope.gates),
133
+ failedGates: gateNamesWith(envelope.gates, 'failed'),
134
+ deferredGates: gateNamesWith(envelope.gates, 'deferred'),
134
135
  prNumber: intOrNull(envelope.pr?.number),
135
136
  mandrelVersion,
136
137
  workerModel: clip(worker.workerModel),
@@ -1,7 +1,9 @@
1
1
  /**
2
2
  * handoff-rescore.js — the handoff runs close's own duplication re-score
3
3
  * before any credit, so close's later re-score over the same tree no-ops;
4
- * and names the duplication rows a branch raised in a post-capture finding.
4
+ * under admitted preflight lanes it scans beside preflight and commits at a
5
+ * join instead. Also names the duplication rows a branch raised in a
6
+ * post-capture finding.
5
7
  */
6
8
 
7
9
  import fs from 'node:fs';
@@ -43,6 +45,42 @@ function settle(ctx, result, readHead) {
43
45
  return { outcome: 'error', detail: result?.reason ?? 'no result' };
44
46
  }
45
47
 
48
+ /** Close's re-score inputs for this handoff. */
49
+ function rescoreInput(ctx) {
50
+ const log = (m) => ctx.progress('duplication-rescore', m);
51
+ return {
52
+ cwd: ctx.cwd,
53
+ worktreePath: ctx.cwd,
54
+ storyId: ctx.storyId,
55
+ baseBranch: ctx.baseBranch,
56
+ storyBranch: ctx.branch,
57
+ baselineRef: ctx.baselineRef,
58
+ config: ctx.config,
59
+ logger: { info: log, warn: log },
60
+ };
61
+ }
62
+
63
+ /** Settle `result`; anything but an `error` records the re-score at HEAD. */
64
+ function record(ctx, result, readHead) {
65
+ const settled = settle(ctx, result, readHead);
66
+ if (settled.outcome !== 'error') {
67
+ ctx.state.duplicationRescore = {
68
+ head: ctx.head,
69
+ partners: result?.partners ?? {},
70
+ };
71
+ }
72
+ return settled;
73
+ }
74
+
75
+ /** The skip a HEAD already re-scored settles; `null` when it was not. */
76
+ function alreadyRescored(ctx) {
77
+ if (ctx.state.duplicationRescore?.head !== ctx.head) return null;
78
+ return {
79
+ outcome: 'skipped',
80
+ detail: `already re-scored at ${ctx.head.slice(0, 12)}`,
81
+ };
82
+ }
83
+
46
84
  /**
47
85
  * Run the re-score once per HEAD; best-effort, it never stops the run. An
48
86
  * `error` records nothing, so a re-run retries.
@@ -53,37 +91,69 @@ function settle(ctx, result, readHead) {
53
91
  * @returns {Promise<{ outcome: string, detail: string }>}
54
92
  */
55
93
  export async function rescoreDuplication(ctx, readHead) {
56
- const prior = ctx.state.duplicationRescore;
57
- if (prior?.head === ctx.head) {
58
- return {
59
- outcome: 'skipped',
60
- detail: `already re-scored at ${ctx.head.slice(0, 12)}`,
61
- };
62
- }
63
- const log = (m) => ctx.progress('duplication-rescore', m);
94
+ const already = alreadyRescored(ctx);
95
+ if (already) return already;
64
96
  let result;
65
97
  try {
66
- result = await ctx.runDuplicationRescore({
67
- cwd: ctx.cwd,
68
- worktreePath: ctx.cwd,
69
- storyId: ctx.storyId,
70
- baseBranch: ctx.baseBranch,
71
- storyBranch: ctx.branch,
72
- baselineRef: ctx.baselineRef,
73
- config: ctx.config,
74
- logger: { info: log, warn: log },
75
- });
98
+ result = await ctx.runDuplicationRescore(rescoreInput(ctx));
76
99
  } catch (err) {
77
100
  return { outcome: 'error', detail: `threw: ${err?.message ?? err}` };
78
101
  }
79
- const settled = settle(ctx, result, readHead);
80
- if (settled.outcome !== 'error') {
81
- ctx.state.duplicationRescore = {
82
- head: ctx.head,
83
- partners: result?.partners ?? {},
102
+ return record(ctx, result, readHead);
103
+ }
104
+
105
+ /**
106
+ * Start close's scan beside preflight at `ctx.head`; it writes nothing.
107
+ *
108
+ * @param {object} ctx `ctx.scanDuplicationRescore` is close's scan.
109
+ * @returns {{ already?: object, input?: object, done?: Promise<{ scan?: object, error?: string, durationMs: number }> }}
110
+ */
111
+ export function startDuplicationScan(ctx) {
112
+ const already = alreadyRescored(ctx);
113
+ if (already) return { already };
114
+ const input = rescoreInput(ctx);
115
+ const startedAt = ctx.now();
116
+ const done = Promise.resolve()
117
+ .then(() => ctx.scanDuplicationRescore(input))
118
+ .then(
119
+ (scan) => ({ scan }),
120
+ (err) => ({ error: `threw: ${err?.message ?? err}` }),
121
+ )
122
+ .then((out) => ({ ...out, durationMs: ctx.now() - startedAt }));
123
+ return { input, done };
124
+ }
125
+
126
+ /**
127
+ * Await the scan and, when rows moved, apply them through close's commit.
128
+ * The result carries the scan's own wall time and its concurrency marker.
129
+ *
130
+ * @param {object} ctx `ctx.applyDuplicationRescore` is close's apply.
131
+ * @param {ReturnType<typeof startDuplicationScan>} started
132
+ * @param {() => string|null} readHead
133
+ * @returns {Promise<{ name: string, outcome: string, detail: string, concurrentWith: string, durationMs: number }>}
134
+ */
135
+ export async function joinDuplicationScan(ctx, started, readHead) {
136
+ const step = { name: 'duplication-rescore', concurrentWith: 'preflight' };
137
+ if (started.already) return { ...step, ...started.already, durationMs: 0 };
138
+ const { scan, error, durationMs } = await started.done;
139
+ const base = { ...step, durationMs };
140
+ if (error) return { ...base, outcome: 'error', detail: error };
141
+ if (!scan?.changed) {
142
+ const result = scan?.reason
143
+ ? scan
144
+ : { reason: 'unchanged', partners: scan?.partners };
145
+ return { ...base, ...record(ctx, result, readHead) };
146
+ }
147
+ try {
148
+ const result = await ctx.applyDuplicationRescore(scan, started.input);
149
+ return { ...base, ...record(ctx, result, readHead) };
150
+ } catch (err) {
151
+ return {
152
+ ...base,
153
+ outcome: 'error',
154
+ detail: `threw: ${err?.message ?? err}`,
84
155
  };
85
156
  }
86
- return settled;
87
157
  }
88
158
 
89
159
  /** @returns {string} the configured duplication baseline path. */
@@ -56,6 +56,17 @@ function textIncludesAny(text, markers) {
56
56
  return markers.some((marker) => lower.includes(marker));
57
57
  }
58
58
 
59
+ function describeExhaustion(prProbe) {
60
+ const mergeState = `mergeStateStatus=${prProbe?.mergeStateStatus ?? 'n/a'}`;
61
+ if (prProbe?.checksStatus === 'success') {
62
+ return `watch budget exhausted with every check green but the PR did not land (${mergeState}, autoMergeArmed=${prProbe?.autoMergeArmed ?? 'unknown'}, inMergeQueue=${prProbe?.inMergeQueue ?? 'unknown'})`;
63
+ }
64
+ if (prProbe?.checksStatus === 'unknown') {
65
+ return `watch budget exhausted with no checks reported (${mergeState})`;
66
+ }
67
+ return `watch budget exhausted with an unrecognised checks status (${prProbe?.checksStatus ?? 'unknown'})`;
68
+ }
69
+
59
70
  /** The most specific `api-race-other` reason the signals allow. */
60
71
  function describeApiRaceFallback(prProbe, budget) {
61
72
  if (prProbe?.error) {
@@ -67,7 +78,7 @@ function describeApiRaceFallback(prProbe, budget) {
67
78
  return `PR did not land although its failing checks are not required (mergeStateStatus=${prProbe?.mergeStateStatus ?? 'n/a'}); the red checks are not the block — check that auto-merge is still armed`;
68
79
  }
69
80
  if (budget && budget.exhausted === true) {
70
- return `watch budget exhausted with an unrecognised checks status (${prProbe?.checksStatus ?? 'unknown'})`;
81
+ return describeExhaustion(prProbe);
71
82
  }
72
83
  return 'no definitive block signal observed; classified as a transient API race or other condition';
73
84
  }
@@ -31,6 +31,15 @@ export function probeSettlesAsyncWait(checksStatus) {
31
31
  return checksStatus !== 'success' && checksStatus !== 'failure';
32
32
  }
33
33
 
34
+ /** Every `checksStatus` a merge-wait probe carries: the rollup's four, plus `pending` on a probe error. */
35
+ export const CHECKS_STATUSES = Object.freeze([
36
+ 'success',
37
+ 'failure',
38
+ 'still-running',
39
+ 'pending',
40
+ 'unknown',
41
+ ]);
42
+
34
43
  /** Bounds every `gh` spawn so a hang degrades to the probe-error path. */
35
44
  export const MERGE_WAIT_GH_TIMEOUT_MS = 60_000;
36
45
 
@@ -27,13 +27,13 @@ export const MERGE_QUEUE_REFUSAL = /when merge queue enabled/i;
27
27
  /** Block class: a merge-queue base reached over the REST transport. */
28
28
  export const MERGE_QUEUE_REST_BLOCK_CLASS = 'merge-queue-rest-unsupported';
29
29
 
30
- /** The remedy that block carries: enqueueing is GraphQL-only. */
30
+ /** The remedy that block carries: the CCR route refused to arm the queue base. */
31
31
  export const MERGE_QUEUE_REST_REMEDY =
32
32
  "The PR's base branch requires a merge queue, and this session reaches GitHub over " +
33
- 'repo-scoped REST only (GraphQL answers 403). Enqueueing is GraphQL-only, and a direct ' +
34
- 'merge would bypass the queue, so close did not merge. Enqueue the PR from a session ' +
35
- 'that can reach GraphQL (arm auto-merge there) or from the GitHub UI, then confirm with ' +
36
- '`node .agents/scripts/single-story-confirm-merge.js --story <id>`.';
33
+ 'repo-scoped REST only (GraphQL answers 403). The CCR auto-merge route refused this PR, ' +
34
+ 'and a direct merge would bypass the queue, so close did not merge. Enqueue the PR from a ' +
35
+ 'session that can reach GraphQL (arm auto-merge there) or from the GitHub UI, then confirm ' +
36
+ 'with `node .agents/scripts/single-story-confirm-merge.js --story <id>`.';
37
37
 
38
38
  /**
39
39
  * REST reading: the base's active rulesets name a `merge_queue` rule.
@@ -153,10 +153,17 @@ async function dequeuePullRequest({ prNodeId, gh }) {
153
153
  }
154
154
  }
155
155
 
156
+ function queueArmOutcome(result) {
157
+ return result.mergeOnGreen
158
+ ? { enabled: false, mergeQueue: true, reason: MERGE_QUEUE_REST_BLOCK_CLASS }
159
+ : { enabled: true, mergeQueue: true };
160
+ }
161
+
156
162
  /**
157
163
  * Arm on a merge-queue base: a bare `--auto`, and never the direct-merge
158
164
  * fallback — a merge that bypassed the queue would defeat the protection it
159
- * exists for.
165
+ * exists for. Over REST a CCR refusal resolves with `mergeOnGreen`, which on
166
+ * a queue base is the REST block, never an arm.
160
167
  *
161
168
  * @returns {Promise<{ enabled: boolean, mergeQueue: true, reason?: string }>}
162
169
  */
@@ -165,7 +172,7 @@ export async function armForMergeQueue({ exec, prNumber, armCwd }) {
165
172
  const result = await exec(['pr', 'merge', String(prNumber), '--auto'], {
166
173
  cwd: armCwd,
167
174
  });
168
- if (result.status === 0) return { enabled: true, mergeQueue: true };
175
+ if (result.status === 0) return queueArmOutcome(result);
169
176
  return {
170
177
  enabled: false,
171
178
  mergeQueue: true,
@@ -9,11 +9,7 @@
9
9
  * repo's `delete_branch_on_merge` owns the remote branch reap.
10
10
  */
11
11
 
12
- import {
13
- gh as defaultGh,
14
- describeGhFailure,
15
- prTransportOf,
16
- } from '../../../gh-exec.js';
12
+ import { gh as defaultGh, describeGhFailure } from '../../../gh-exec.js';
17
13
  import { REST_MERGE_ON_GREEN } from '../../../gh-pr-rest.js';
18
14
  import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
19
15
  import {
@@ -24,7 +20,6 @@ import {
24
20
  armForMergeQueue,
25
21
  disarmByDequeue,
26
22
  MERGE_QUEUE_REFUSAL,
27
- MERGE_QUEUE_REST_BLOCK_CLASS,
28
23
  readMergeQueueState,
29
24
  } from '../../merge-queue.js';
30
25
 
@@ -145,30 +140,12 @@ export async function enableAutoMergeWith({
145
140
  resolveArmCwd = resolveAutoMergeArmCwd,
146
141
  queueRequired = false,
147
142
  }) {
148
- const facade = gh ?? defaultGh;
149
- const refused = await refuseQueueOverRest(facade, queueRequired);
150
- if (refused) return refused;
151
- const exec = runner ?? makeDefaultGhAutoMergeRunner(facade);
143
+ const exec = runner ?? makeDefaultGhAutoMergeRunner(gh ?? defaultGh);
152
144
  const armCwd = resolveArmCwd(cwd);
153
145
  const arm = queueRequired ? armForMergeQueue : armNativeAutoMerge;
154
146
  return arm({ exec, prNumber, armCwd });
155
147
  }
156
148
 
157
- /**
158
- * A merge-queue base over the REST transport: enqueueing is GraphQL-only, and
159
- * a direct merge would bypass the queue, so the arm refuses.
160
- *
161
- * @returns {Promise<{ enabled: false, mergeQueue: true, reason: string }|null>}
162
- */
163
- async function refuseQueueOverRest(facade, queueRequired) {
164
- if (!queueRequired || (await prTransportOf(facade)) !== 'rest') return null;
165
- return {
166
- enabled: false,
167
- mergeQueue: true,
168
- reason: MERGE_QUEUE_REST_BLOCK_CLASS,
169
- };
170
- }
171
-
172
149
  /** The hand-run equivalent of the arm, for an operator-facing remedy. */
173
150
  export function manualArmCommand({ prNumber, queueRequired = false }) {
174
151
  return queueRequired
@@ -35,7 +35,7 @@ import {
35
35
  * resolveConfigImpl?: typeof resolveConfig,
36
36
  * progress: (tag: string, msg: string) => void,
37
37
  * }} args
38
- * @returns {Promise<{ changedPaths: string[], creditedCommit: string|null, baselineRef?: string, decision: object|null }>}
38
+ * @returns {Promise<{ changedPaths: string[], creditedCommit: string|null, baselineRef?: string, decision: object|null, kind: string, resolvedBaselineFiles: string[] }>}
39
39
  * The pre-sync head is the credited commit; a skipped sync pins `baselineRef`.
40
40
  */
41
41
  export async function runBaseSyncPhase({
@@ -91,6 +91,11 @@ export async function runBaseSyncPhase({
91
91
  })) {
92
92
  progress('SYNC', line);
93
93
  }
94
+ return phaseResult(syncResult, resolved);
95
+ }
96
+
97
+ /** What the gate chain reads from a completed sync. */
98
+ function phaseResult(syncResult, resolvedBaselineFiles) {
94
99
  return {
95
100
  changedPaths: Array.isArray(syncResult.changedPaths)
96
101
  ? syncResult.changedPaths
@@ -98,6 +103,8 @@ export async function runBaseSyncPhase({
98
103
  creditedCommit: syncResult.preSyncHead ?? null,
99
104
  baselineRef: syncResult.baselineRef,
100
105
  decision: syncResult.decision ?? null,
106
+ kind: syncResult.kind,
107
+ resolvedBaselineFiles,
101
108
  };
102
109
  }
103
110
 
@@ -14,12 +14,14 @@ import {
14
14
  sourcedTimings,
15
15
  summarizeLockEvents,
16
16
  } from '../../../close-lock-events.js';
17
+ import { applyBaseSyncCiDeferral as defaultApplyBaseSyncCiDeferral } from '../../../close-validation/base-sync-revalidation.js';
17
18
  import {
18
19
  BASELINES_GATE_NAMES,
19
20
  buildDefaultGates as defaultBuildDefaultGates,
20
21
  } from '../../../close-validation/gates.js';
21
22
  import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
22
23
  import { applyTestDelta as defaultApplyTestDelta } from '../../../close-validation/test-delta.js';
24
+ import { suiteGateDeferral } from '../../../coverage-deferral.js';
23
25
  import { LOCK_WAIT_EXPIRED_EXIT_CODE } from '../../../full-suite-lock.js';
24
26
  import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
25
27
  import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
@@ -36,11 +38,12 @@ import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
36
38
  * baseBranch: string,
37
39
  * storyBranch?: string,
38
40
  * storyId: number,
39
- * baseSync?: { changedPaths: string[], creditedCommit: string|null, baselineRef?: string }|null,
41
+ * baseSync?: { changedPaths: string[], creditedCommit: string|null, baselineRef?: string, kind?: string, resolvedBaselineFiles?: string[] }|null,
40
42
  * progress: (tag: string, msg: string) => void,
41
43
  * runCloseValidation?: typeof defaultRunCloseValidation,
42
44
  * buildDefaultGates?: typeof defaultBuildDefaultGates,
43
45
  * applyTestDelta?: typeof defaultApplyTestDelta,
46
+ * applyBaseSyncCiDeferral?: typeof defaultApplyBaseSyncCiDeferral,
44
47
  * runPreGateSteps?: typeof defaultRunPreGateSteps,
45
48
  * runScopedFormatAutofix?: Function,
46
49
  * runBaselineUpwardWriteback?: Function,
@@ -54,8 +57,11 @@ import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
54
57
  * lockWait: { waitedSeconds: number, expired: boolean, holder?: object }|null,
55
58
  * suiteTimings: { lockWaitMs: number, hostWaitMs: number|null, testRunMs: number, source: 'close', spawns: object[] }|null,
56
59
  * pending: boolean,
60
+ * coverageDeferred?: string|null,
61
+ * revalidation?: object|null,
57
62
  * }>} `pending` (with `gates: null`) when a lock wait expired; any other
58
- * failure throws with `err.closeGate` naming the gate.
63
+ * failure throws with `err.closeGate` naming the gate. `revalidation` is
64
+ * non-null only under `revalidateAfterBaseSync: "ci"`.
59
65
  */
60
66
  export async function runCloseValidationPhase({
61
67
  cwd,
@@ -69,6 +75,7 @@ export async function runCloseValidationPhase({
69
75
  runCloseValidation = defaultRunCloseValidation,
70
76
  buildDefaultGates = defaultBuildDefaultGates,
71
77
  applyTestDelta = defaultApplyTestDelta,
78
+ applyBaseSyncCiDeferral = defaultApplyBaseSyncCiDeferral,
72
79
  runPreGateSteps = defaultRunPreGateSteps,
73
80
  runScopedFormatAutofix,
74
81
  runBaselineUpwardWriteback,
@@ -106,10 +113,10 @@ export async function runCloseValidationPhase({
106
113
  evidenceCwd: cwd,
107
114
  baselineRef: baseSync?.baselineRef,
108
115
  };
109
- const gateList = applyTestDelta(buildDefaultGates(gateOpts), {
110
- ...gateOpts,
111
- baseSync,
112
- });
116
+ const { gates: gateList, revalidation } = buildGateList(
117
+ { buildDefaultGates, applyTestDelta, applyBaseSyncCiDeferral },
118
+ { ...gateOpts, baseSync },
119
+ );
113
120
  reportGateLabels(gateList, progress);
114
121
  const { validation, lockWait, ...timings } = await runGateChain({
115
122
  runCloseValidation,
@@ -139,10 +146,22 @@ export async function runCloseValidationPhase({
139
146
  lockWait,
140
147
  suiteTimings: sourcedTimings(timings, 'close'),
141
148
  pending: false,
142
- coverageDeferred: validation.deferred?.[0]?.reason ?? null,
149
+ coverageDeferred: coverageDeferralReason(validation),
150
+ revalidation,
143
151
  };
144
152
  }
145
153
 
154
+ /** Built gates, then the `test` delta, then the post-merge CI deferral. */
155
+ function buildGateList(build, opts) {
156
+ const gates = build.applyTestDelta(build.buildDefaultGates(opts), opts);
157
+ return build.applyBaseSyncCiDeferral(gates, opts);
158
+ }
159
+
160
+ /** The suite gate's deferral reason; a typecheck or lint deferral is not one. */
161
+ function coverageDeferralReason(validation) {
162
+ return suiteGateDeferral(validation.deferred)?.reason ?? null;
163
+ }
164
+
146
165
  /** A labelled gate (the `test` delta re-credit) names itself on the progress line. */
147
166
  function reportGateLabels(gateList, progress) {
148
167
  for (const gate of gateList) {
@@ -48,6 +48,7 @@ import {
48
48
  ADVISORY_GATE_INCONCLUSIVE_CLASS,
49
49
  ADVISORY_GATE_RED_CLASS,
50
50
  CHECKS_FAILED_CLASS,
51
+ CHECKS_STATUSES,
51
52
  DEFAULT_INTERVAL_SECONDS,
52
53
  DEFAULT_MAX_BUDGET_SECONDS,
53
54
  decideAdvisoryGateBlock,
@@ -1159,9 +1160,20 @@ function singleProbeOrContinue(limits, overBudget, checksStatus) {
1159
1160
  return settles ? 'single-probe' : 'continue';
1160
1161
  }
1161
1162
 
1163
+ /** A verdict no budget changes: merged, closed, or a status outside the closed vocabulary. */
1164
+ function settledVerdictOf(probe) {
1165
+ if (isPrMerged(probe)) return 'merged';
1166
+ if (probe.state === 'CLOSED') return 'closed';
1167
+ const status = probe.checksStatus;
1168
+ if (status != null && !CHECKS_STATUSES.includes(status)) {
1169
+ return 'checks-status-unrecognised';
1170
+ }
1171
+ return null;
1172
+ }
1173
+
1162
1174
  /**
1163
- * Pure: state + probe + clock → next state and verdict. `merged`, `closed`
1164
- * and `checks-failed` are definitive; `budget-exhausted`, `wait-bound`,
1175
+ * Pure: state + probe + clock → next state and verdict. `merged`, `closed`,
1176
+ * `checks-status-unrecognised` and `checks-failed` are definitive; `budget-exhausted`, `wait-bound`,
1165
1177
  * `single-probe` and `continue` hold only if the loop's advisory check does not block first.
1166
1178
  * The two clock reads (wait bound, then budget) keep a stepping test clock's
1167
1179
  * call sequence.
@@ -1202,10 +1214,8 @@ export function decideMergeWaitPoll({
1202
1214
  maxBudgetSeconds: limits.maxBudgetSeconds,
1203
1215
  },
1204
1216
  };
1205
- if (isPrMerged(probe)) return { state: polled, verdict: 'merged', ...timing };
1206
- if (probe.state === 'CLOSED') {
1207
- return { state: polled, verdict: 'closed', ...timing };
1208
- }
1217
+ const settled = settledVerdictOf(probe);
1218
+ if (settled) return { state: polled, verdict: settled, ...timing };
1209
1219
  // No remaining budget turns a red required check green; fail fast.
1210
1220
  const failFast = decideMergeWaitFailFast({
1211
1221
  probe,
@@ -1280,9 +1290,19 @@ async function settleChecksFailed(ctx, decision, probe) {
1280
1290
  });
1281
1291
  }
1282
1292
 
1293
+ function settleUnrecognisedChecks(ctx, decision, probe) {
1294
+ return blockWith(ctx, {
1295
+ prProbe: probe,
1296
+ budget: { exhausted: false, elapsedSeconds: decision.elapsedSeconds },
1297
+ blockClassOverride: CLOSED_UNMERGED_BLOCK_CLASS,
1298
+ reasonOverride: `unrecognised checks status (${probe.checksStatus})`,
1299
+ });
1300
+ }
1301
+
1283
1302
  const DEFINITIVE_SETTLERS = Object.freeze({
1284
1303
  merged: settleMerged,
1285
1304
  closed: settleClosed,
1305
+ 'checks-status-unrecognised': settleUnrecognisedChecks,
1286
1306
  'checks-failed': settleChecksFailed,
1287
1307
  });
1288
1308
 
@@ -1368,12 +1388,19 @@ async function recoverOpenPr(ctx, decision, probe) {
1368
1388
  /**
1369
1389
  * Close owns the merge when the CCR route would not arm it: the arm said so,
1370
1390
  * or (a `--wait` resume, which has no arm outcome) the PR transport is REST
1371
- * and GitHub holds no auto-merge request. Only a PR close itself armed.
1391
+ * and GitHub holds no auto-merge request. Only a PR close itself armed, and
1392
+ * never on a queue base: GitHub clears the request when it enqueues.
1372
1393
  *
1373
1394
  * @returns {Promise<boolean>}
1374
1395
  */
1375
1396
  async function closeOwnsMerge(ctx, probe) {
1376
- if (ctx.closeArmed !== true) return false;
1397
+ if (ctx.closeArmed !== true || !(await restOwnsMerge(ctx, probe))) {
1398
+ return false;
1399
+ }
1400
+ return !(await baseRequiresQueue(ctx));
1401
+ }
1402
+
1403
+ async function restOwnsMerge(ctx, probe) {
1377
1404
  if (ctx.autoMergeReason === REST_MERGE_ON_GREEN) return true;
1378
1405
  return (
1379
1406
  probe.autoMergeArmed !== true &&
@@ -1381,6 +1408,18 @@ async function closeOwnsMerge(ctx, probe) {
1381
1408
  );
1382
1409
  }
1383
1410
 
1411
+ /** Read once per invocation; a failed read (`null`) is not a queue. */
1412
+ function baseRequiresQueue(ctx) {
1413
+ ctx.queueRequiredRead ??= ctx
1414
+ .readMergeQueueStateFn({
1415
+ prNumber: ctx.prNumber,
1416
+ gh: ctx.waitGh,
1417
+ timeoutMs: ctx.ghTimeoutMs,
1418
+ })
1419
+ .then((queue) => queue?.queueRequired === true);
1420
+ return ctx.queueRequiredRead;
1421
+ }
1422
+
1384
1423
  function isCleanAndGreen(probe) {
1385
1424
  return (
1386
1425
  probe?.state === 'OPEN' &&
@@ -1557,6 +1596,7 @@ function neverArmedOverride(autoMergeReason, advisoryGate) {
1557
1596
  * @param {Function} [args.disarmAutoMergeFn]
1558
1597
  * @param {Function} [args.recordRequiredRedFn] The shared first-red handling (disarm + CI digest).
1559
1598
  * @param {Function} [args.mergeOnGreenFn] The merge-on-green squash-merge (`auto-merge.js#mergeOnGreen`).
1599
+ * @param {Function} [args.readMergeQueueStateFn] Whether the base requires a merge queue.
1560
1600
  * @param {object} [args.recoverySeams] DIRTY-sync / re-arm seams (`mergeWaitRecoverySeams`).
1561
1601
  * @param {(ms: number) => Promise<void>} [args.sleepFn]
1562
1602
  * @param {() => number} [args.nowMsFn]
@@ -1577,6 +1617,7 @@ export async function runConfirmMergePhase({
1577
1617
  disarmAutoMergeFn = disarmAutoMerge,
1578
1618
  recordRequiredRedFn = defaultRecordRequiredRed,
1579
1619
  mergeOnGreenFn = mergeOnGreen,
1620
+ readMergeQueueStateFn = readMergeQueueState,
1580
1621
  sleepFn = defaultSleep,
1581
1622
  nowMsFn = Date.now,
1582
1623
  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
@@ -1625,6 +1666,7 @@ export async function runConfirmMergePhase({
1625
1666
  disarmAutoMergeFn,
1626
1667
  recordRequiredRedFn,
1627
1668
  mergeOnGreenFn,
1669
+ readMergeQueueStateFn,
1628
1670
  nowMsFn,
1629
1671
  ghTimeoutMs,
1630
1672
  waitGh: args.injectedGh ?? defaultGh,
@@ -165,14 +165,15 @@ export async function finishWithMergeWait(prCtx, deps) {
165
165
  return { success: terminal.status === 'landed', result, terminal };
166
166
  }
167
167
 
168
- /** The close-only envelope fields both finishes carry. */
168
+ /** The close-only envelope fields both finishes carry; an undefined one is dropped. */
169
169
  function closeEnvelopeFields({
170
170
  lockWait,
171
171
  suiteTimings,
172
172
  baseSync,
173
173
  pushOutcome,
174
+ revalidation,
174
175
  }) {
175
- return { lockWait, suiteTimings, baseSync, pushOutcome };
176
+ return { lockWait, suiteTimings, baseSync, pushOutcome, revalidation };
176
177
  }
177
178
 
178
179
  /**
@@ -104,13 +104,19 @@ export async function runPrePushPhases(ctx, deps) {
104
104
  }
105
105
  throw err;
106
106
  }
107
- const gates = validation?.gates ?? null;
108
- ctx.setObservedGates(gates);
107
+ ctx.setObservedGates(validation?.gates ?? null);
108
+ return validatedResult(validation);
109
+ }
110
+
111
+ /** The pre-push result of a gate chain that ran. */
112
+ function validatedResult(validation) {
109
113
  return {
110
- validationGates: gates,
114
+ validationGates: validation?.gates ?? null,
111
115
  lockWait: validation?.lockWait ?? null,
112
116
  suiteTimings: validation?.suiteTimings ?? null,
113
117
  pending: validation?.pending === true,
114
118
  coverageDeferred: validation?.coverageDeferred ?? null,
119
+ // Undefined, not null, so the envelope omits it outside the `ci` mode.
120
+ revalidation: validation?.revalidation ?? undefined,
115
121
  };
116
122
  }
@@ -170,15 +170,18 @@ function baselinesEnvelopeGates(validationGates) {
170
170
  }
171
171
 
172
172
  /**
173
- * A capture deferred to CI is the one capture outcome a reviewer must see.
173
+ * Every gate deferred to CI (typecheck, lint, coverage-capture): the one
174
+ * outcome of those gates a reviewer must see.
174
175
  *
175
176
  * @param {Record<string, string>|null|undefined} validationGates
176
177
  * @returns {Record<string, string>}
177
178
  */
178
- function deferredCaptureGate(validationGates) {
179
- return validationGates?.['coverage-capture'] === 'deferred'
180
- ? { 'coverage-capture': 'deferred' }
181
- : {};
179
+ function deferredGates(validationGates) {
180
+ const out = {};
181
+ for (const [name, outcome] of Object.entries(validationGates ?? {})) {
182
+ if (outcome === 'deferred') out[name] = outcome;
183
+ }
184
+ return out;
182
185
  }
183
186
 
184
187
  /**
@@ -220,7 +223,7 @@ export function closeEnvelopeGates(
220
223
  return {
221
224
  validation: options.skipValidation ? 'skipped' : 'passed',
222
225
  ...baselinesEnvelopeGates(validationGates),
223
- ...deferredCaptureGate(validationGates),
226
+ ...deferredGates(validationGates),
224
227
  baseSync: options.skipSync ? 'skipped' : 'passed',
225
228
  codeReview: codeReviewGate(
226
229
  reviewOverride,
@@ -456,6 +456,7 @@ function buildPrContext(ctx, deps) {
456
456
  lockWait: ctx.prePush.lockWait,
457
457
  baseSync: ctx.baseSync?.decision ?? null,
458
458
  pushOutcome: ctx.pr.pushOutcome ?? null,
459
+ revalidation: ctx.prePush.revalidation,
459
460
  suiteTimings: envelopeSuiteTimings(ctx, deps),
460
461
  gates: closeEnvelopeGates(
461
462
  options,