mandrel 2.93.0 → 2.94.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 (26) hide show
  1. package/.agents/docs/configuration.md +8 -3
  2. package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
  3. package/.agents/schemas/story-deliver-terminal.schema.json +1 -0
  4. package/.agents/scripts/lib/duplicate-search.js +52 -18
  5. package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js +47 -20
  6. package/.agents/scripts/lib/gh-exec.js +94 -24
  7. package/.agents/scripts/lib/gh-pr-rest.js +371 -0
  8. package/.agents/scripts/lib/orchestration/board-graphql-latch.js +75 -0
  9. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +73 -29
  10. package/.agents/scripts/lib/orchestration/column-sync.js +23 -21
  11. package/.agents/scripts/lib/orchestration/merge-block-class.js +3 -1
  12. package/.agents/scripts/lib/orchestration/merge-queue.js +49 -4
  13. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +2 -2
  14. package/.agents/scripts/lib/orchestration/required-checks.js +72 -12
  15. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +132 -58
  16. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +92 -9
  17. package/.agents/scripts/lib/orchestration/single-story-close/phases/graphql-preflight.js +41 -18
  18. package/.agents/scripts/lib/orchestration/ticketing/transition.js +1 -1
  19. package/.agents/scripts/providers/github/board-add.js +3 -3
  20. package/.agents/scripts/providers/github/compose.js +2 -0
  21. package/.agents/scripts/providers/github/errors.js +41 -0
  22. package/.agents/scripts/providers/github/sub-issues-rest.js +55 -0
  23. package/.agents/scripts/providers/github/sub-issues.js +9 -1
  24. package/.agents/scripts/single-story-confirm-merge.js +2 -0
  25. package/docs/CHANGELOG.md +12 -0
  26. package/package.json +1 -1
@@ -688,9 +688,14 @@ environment variable identifies one person:
688
688
  supplies your connected GitHub account's credential for REST calls.
689
689
 
690
690
  The proxy answers **all** GitHub GraphQL with HTTP 403, even when you set
691
- your own token. Projects v2 is GraphQL-only, so board Status never syncs
692
- from a cloud session. Labels stay authoritative, and each skipped Status flip
693
- is reported as a warning.
691
+ your own token. Close detects that during `init` and runs the pull-request
692
+ surface over repo-scoped REST instead: it opens the PR, arms auto-merge
693
+ through the proxy's route or, when that route refuses, squash-merges the PR
694
+ itself once it is CLEAN with green checks, and confirms the land. A base
695
+ branch behind a merge queue still needs a session that reaches GraphQL.
696
+ Projects v2 is GraphQL-only, so board Status never syncs from a cloud
697
+ session. Labels stay authoritative, and each skipped Status flip is reported
698
+ as a warning.
694
699
 
695
700
  The handle has to be a user who can be assigned. GitHub's add-assignees
696
701
  endpoint silently ignores a login it cannot assign, such as an Organization,
@@ -31,7 +31,8 @@
31
31
  "api-race-other",
32
32
  "predicate-refused",
33
33
  "advisory-gate-red",
34
- "advisory-gate-inconclusive"
34
+ "advisory-gate-inconclusive",
35
+ "merge-queue-rest-unsupported"
35
36
  ]
36
37
  },
37
38
  "reason": { "type": "string", "minLength": 1 },
@@ -141,6 +141,7 @@
141
141
  "predicate-refused",
142
142
  "advisory-gate-red",
143
143
  "advisory-gate-inconclusive",
144
+ "merge-queue-rest-unsupported",
144
145
  "merged-flip-failed"
145
146
  ]
146
147
  },
@@ -4,6 +4,7 @@
4
4
  * fallback errors propagate verbatim to the caller.
5
5
  */
6
6
 
7
+ import { isProxyScopeRefusal } from '../providers/github/errors.js';
7
8
  import { Logger } from './Logger.js';
8
9
  import { TYPE_LABELS } from './label-constants.js';
9
10
 
@@ -232,10 +233,53 @@ async function fetchOpenStoriesViaList(provider) {
232
233
  return issues.map(normalizeIssue);
233
234
  }
234
235
 
236
+ // A proxy refusal of `/search/issues` holds for the whole process.
237
+ let searchRefusedByProxy = false;
238
+
239
+ /**
240
+ * Search hits, or `null` to use the label listing. An empty search is
241
+ * evidence about the AND-ed query, not about the backlog.
242
+ *
243
+ * @param {object} provider
244
+ * @param {string} seed
245
+ * @param {boolean} hasList
246
+ * @returns {Promise<Array<object>|null>}
247
+ */
248
+ async function trySearch(provider, seed, hasList) {
249
+ try {
250
+ const hits = await fetchOpenStoriesViaSearch(provider, seed);
251
+ if (hits.length > 0 || !hasList) return hits;
252
+ Logger.info(
253
+ '[duplicate-search] narrowed search matched no open Stories; ' +
254
+ 'falling back to listIssuesByLabel + client-side ranking',
255
+ );
256
+ } catch (err) {
257
+ if (!hasList) throw err;
258
+ reportSearchFailure(err);
259
+ }
260
+ return null;
261
+ }
262
+
263
+ /** @param {unknown} err */
264
+ function reportSearchFailure(err) {
265
+ if (isProxyScopeRefusal(err)) {
266
+ searchRefusedByProxy = true;
267
+ Logger.info(
268
+ '[duplicate-search] the Claude Code cloud proxy refuses /search/issues ' +
269
+ 'in this session; ranking from listIssuesByLabel for the rest of the run',
270
+ );
271
+ return;
272
+ }
273
+ const msg = typeof err?.message === 'string' ? err.message : String(err);
274
+ Logger.warn(
275
+ `[duplicate-search] search-based candidate fetch failed (${msg}); ` +
276
+ 'falling back to listIssuesByLabel',
277
+ );
278
+ }
279
+
235
280
  /**
236
281
  * Search first; fall back to the label listing when search errors, is
237
- * unavailable, or returns no hits. An empty search is evidence about the
238
- * AND-ed query, not about the backlog.
282
+ * unavailable, was refused by the cloud proxy, or returns no hits.
239
283
  *
240
284
  * @param {object} provider
241
285
  * @param {string} seed
@@ -254,22 +298,9 @@ async function fetchOpenStoryCandidates(provider, seed) {
254
298
  );
255
299
  }
256
300
 
257
- if (hasSearch) {
258
- try {
259
- const hits = await fetchOpenStoriesViaSearch(provider, seed);
260
- if (hits.length > 0 || !hasList) return hits;
261
- Logger.info(
262
- '[duplicate-search] narrowed search matched no open Stories; ' +
263
- 'falling back to listIssuesByLabel + client-side ranking',
264
- );
265
- } catch (err) {
266
- if (!hasList) throw err;
267
- const msg = typeof err?.message === 'string' ? err.message : String(err);
268
- Logger.warn(
269
- `[duplicate-search] search-based candidate fetch failed (${msg}); ` +
270
- 'falling back to listIssuesByLabel',
271
- );
272
- }
301
+ if (hasSearch && !(hasList && searchRefusedByProxy)) {
302
+ const hits = await trySearch(provider, seed, hasList);
303
+ if (hits) return hits;
273
304
  }
274
305
 
275
306
  return fetchOpenStoriesViaList(provider);
@@ -323,4 +354,7 @@ export const __test = {
323
354
  SEARCH_RESULT_CAP,
324
355
  buildIssueUrl,
325
356
  buildEpicUrl: buildIssueUrl,
357
+ resetProxySearchRefusal() {
358
+ searchRefusedByProxy = false;
359
+ },
326
360
  };
@@ -96,10 +96,24 @@ function normalizeIssue(raw) {
96
96
  const number = typeof raw.number === 'number' ? raw.number : null;
97
97
  if (number === null) return null;
98
98
  const title = typeof raw.title === 'string' ? raw.title : '';
99
- const url = typeof raw.url === 'string' ? raw.url : '';
100
99
  const intake =
101
100
  typeof raw.body === 'string' && raw.body.includes(CI_GAP_INTAKE_MARKER);
102
- return { number, title, url, labels: normalizeLabels(raw.labels), intake };
101
+ return {
102
+ number,
103
+ title,
104
+ url: issueUrl(raw),
105
+ labels: normalizeLabels(raw.labels),
106
+ intake,
107
+ };
108
+ }
109
+
110
+ /**
111
+ * @param {{ html_url?: unknown, url?: unknown }} raw
112
+ * @returns {string}
113
+ */
114
+ function issueUrl(raw) {
115
+ if (typeof raw.html_url === 'string') return raw.html_url;
116
+ return typeof raw.url === 'string' ? raw.url : '';
103
117
  }
104
118
 
105
119
  /**
@@ -115,6 +129,30 @@ function normalizeLabels(raw) {
115
129
  .filter((name) => typeof name === 'string');
116
130
  }
117
131
 
132
+ const REST_PER_PAGE_MAX = 100;
133
+
134
+ /**
135
+ * REST, not `gh issue list` (GraphQL, refused in cloud sessions).
136
+ *
137
+ * @param {{ owner: string, repo: string, label: string, limit: number }} opts
138
+ * @returns {string[]}
139
+ */
140
+ function restIssuesArgs({ owner, repo, label, limit }) {
141
+ const perPage = Math.min(Math.max(1, limit), REST_PER_PAGE_MAX);
142
+ return [
143
+ 'api',
144
+ '-X',
145
+ 'GET',
146
+ `repos/${owner}/${repo}/issues`,
147
+ '-f',
148
+ 'state=open',
149
+ '-f',
150
+ `labels=${label}`,
151
+ '-f',
152
+ `per_page=${perPage}`,
153
+ ];
154
+ }
155
+
118
156
  /**
119
157
  * @param {object} opts
120
158
  * @param {string} opts.owner
@@ -126,21 +164,7 @@ function normalizeLabels(raw) {
126
164
  * @returns {Promise<{ issues: object[], error: string|null }>}
127
165
  */
128
166
  async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
129
- const args = [
130
- 'issue',
131
- 'list',
132
- '--repo',
133
- `${owner}/${repo}`,
134
- '--state',
135
- 'open',
136
- '--label',
137
- label,
138
- '--json',
139
- 'number,title,labels,url,body',
140
- '--limit',
141
- String(limit),
142
- ];
143
-
167
+ const args = restIssuesArgs({ owner, repo, label, limit });
144
168
  const result = await runGh({ ghPath, args, spawnImpl });
145
169
 
146
170
  if (
@@ -155,15 +179,18 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
155
179
  if (!Array.isArray(parsed)) {
156
180
  return {
157
181
  issues: [],
158
- error: `gh issue list returned non-array JSON for label "${label}"`,
182
+ error: `gh api issues returned non-array JSON for label "${label}"`,
159
183
  };
160
184
  }
161
- const issues = parsed.map(normalizeIssue).filter((issue) => issue !== null);
185
+ const issues = parsed
186
+ .filter((row) => !row?.pull_request)
187
+ .map(normalizeIssue)
188
+ .filter((issue) => issue !== null);
162
189
  return { issues, error: null };
163
190
  } catch (err) {
164
191
  return {
165
192
  issues: [],
166
- error: `Failed to parse gh issue list JSON for label "${label}": ${err.message}`,
193
+ error: `Failed to parse gh api issues JSON for label "${label}": ${err.message}`,
167
194
  };
168
195
  }
169
196
  }
@@ -6,6 +6,7 @@
6
6
  import { spawn as defaultSpawn } from 'node:child_process';
7
7
  import { spawnChild } from './child-exec.js';
8
8
  import { ghEnv, tryGhEnv } from './gh-env.js';
9
+ import { createRestPr } from './gh-pr-rest.js';
9
10
  import {
10
11
  isTransportFailure,
11
12
  sandboxDenialCode,
@@ -355,13 +356,66 @@ export function exec({
355
356
  });
356
357
  }
357
358
 
359
+ /**
360
+ * The process-wide GraphQL-availability verdict, produced once — by close's
361
+ * preflight (`setGraphqlAvailability`) or the facade's first PR-surface use —
362
+ * and read by every facade. Only `unavailable` (the proxy 403) selects REST:
363
+ * `auth-failed` would fail REST the same way, and an inconclusive probe keeps
364
+ * the GraphQL path it was already on.
365
+ */
366
+ let graphqlLatch = null;
367
+ let graphqlLatchPending = null;
368
+
369
+ function transportForVerdict(verdict) {
370
+ return verdict?.verdict === 'unavailable' ? 'rest' : 'graphql';
371
+ }
372
+
373
+ /**
374
+ * Seed (or, with `null`, clear) the latch.
375
+ *
376
+ * @param {{ verdict: string }|null} verdict A `probeGraphqlAvailability` result.
377
+ */
378
+ export function setGraphqlAvailability(verdict) {
379
+ graphqlLatch = verdict ?? null;
380
+ graphqlLatchPending = null;
381
+ }
382
+
383
+ /**
384
+ * Synchronous read for callers that cannot await: true only once the latch
385
+ * has settled on `unavailable`.
386
+ *
387
+ * @returns {boolean}
388
+ */
389
+ export function prSurfaceUsesRest() {
390
+ return transportForVerdict(graphqlLatch) === 'rest';
391
+ }
392
+
393
+ /**
394
+ * The PR transport a facade will use; a facade without one (a test double)
395
+ * is on GraphQL.
396
+ *
397
+ * @param {{ prTransport?: () => Promise<string> }|null|undefined} facade
398
+ * @returns {Promise<'rest'|'graphql'>}
399
+ */
400
+ export async function prTransportOf(facade) {
401
+ if (typeof facade?.prTransport !== 'function') return 'graphql';
402
+ return (await facade.prTransport()) === 'rest' ? 'rest' : 'graphql';
403
+ }
404
+
358
405
  /**
359
406
  * Typed `gh` facade over an `exec` implementation (tests inject a fake).
360
407
  *
361
408
  * @param {Function} execImpl
362
409
  * @param {object} [defaultExecOpts] — per-call options win.
410
+ * @param {{ lazyProbe?: boolean }} [transportOpts] `lazyProbe`: probe GraphQL
411
+ * on first PR-surface use when nothing seeded the latch. Defaults on for the
412
+ * real spawner only, so an injected exec's call log stays its own.
363
413
  */
364
- export function createGh(execImpl = exec, defaultExecOpts = {}) {
414
+ export function createGh(
415
+ execImpl = exec,
416
+ defaultExecOpts = {},
417
+ { lazyProbe = execImpl === exec } = {},
418
+ ) {
365
419
  const execWithDefaults = (opts) => execImpl({ ...defaultExecOpts, ...opts });
366
420
  /**
367
421
  * @param {object} opts
@@ -425,7 +479,7 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
425
479
  }),
426
480
  };
427
481
 
428
- const pr = {
482
+ const graphqlPr = {
429
483
  view: (id, fields) =>
430
484
  execWithDefaults({
431
485
  args: ['pr', 'view', idStr(id), ...jsonFlag(fields)],
@@ -444,6 +498,42 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
444
498
  args: ['pr', 'list', ...flags, ...jsonFlag(fields)],
445
499
  }),
446
500
  };
501
+ const restPr = createRestPr({ api, GhExecError });
502
+
503
+ /** @returns {'rest'|'graphql'|null} null until a lazy probe settles it. */
504
+ function settledPrTransport() {
505
+ if (graphqlLatch) return transportForVerdict(graphqlLatch);
506
+ return lazyProbe ? null : 'graphql';
507
+ }
508
+
509
+ /** @returns {Promise<'rest'|'graphql'>} */
510
+ async function prTransport() {
511
+ const settled = settledPrTransport();
512
+ if (settled) return settled;
513
+ graphqlLatchPending ??= probeGraphqlAvailability({
514
+ ghFacade: { api },
515
+ }).then((verdict) => {
516
+ graphqlLatch ??= verdict;
517
+ return graphqlLatch;
518
+ });
519
+ return transportForVerdict(await graphqlLatchPending);
520
+ }
521
+
522
+ /** Synchronous when the transport is already known, so argv order is unchanged. */
523
+ function routed(name) {
524
+ return (...args) => {
525
+ const settled = settledPrTransport();
526
+ if (settled)
527
+ return (settled === 'rest' ? restPr : graphqlPr)[name](...args);
528
+ return prTransport().then((transport) =>
529
+ (transport === 'rest' ? restPr : graphqlPr)[name](...args),
530
+ );
531
+ };
532
+ }
533
+
534
+ const pr = Object.fromEntries(
535
+ Object.keys(graphqlPr).map((name) => [name, routed(name)]),
536
+ );
447
537
 
448
538
  const label = {
449
539
  create: (name, flags = []) =>
@@ -472,24 +562,11 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
472
562
  };
473
563
 
474
564
  const defaults = Object.freeze({ ...defaultExecOpts });
475
- return { api, issue, pr, label, repo, defaults };
565
+ return { api, issue, pr, label, repo, defaults, prTransport };
476
566
  }
477
567
 
478
568
  export const gh = createGh();
479
569
 
480
- /**
481
- * `gh` routes every one of these through GraphQL, so a GraphQL 403 gates the
482
- * whole PR surface. Kept beside `pr` so the refusal text cannot drift.
483
- */
484
- const GH_PR_SUBCOMMANDS = Object.freeze([
485
- 'view',
486
- 'create',
487
- 'edit',
488
- 'merge',
489
- 'update-branch',
490
- 'list',
491
- ]);
492
-
493
570
  /** Cheapest authenticated GraphQL read: no repo, no extra scope. */
494
571
  const GRAPHQL_PROBE_QUERY = 'query{viewer{login}}';
495
572
 
@@ -577,14 +654,7 @@ export function describeGraphqlPreflight({ verdict, detail } = {}) {
577
654
  suffix
578
655
  );
579
656
  }
580
- const subcommands = GH_PR_SUBCOMMANDS.map((s) => `\`gh pr ${s}\``).join(', ');
581
- return (
582
- 'GitHub GraphQL is unavailable in this session (HTTP 403). `gh` routes the entire pull-request ' +
583
- `surface through GraphQL — ${subcommands} — so this close can neither open, inspect, nor merge ` +
584
- 'a pull request, and every later phase would fail the same way. Retrying here will not help: ' +
585
- 're-run the close from a local session, where GraphQL is reachable.' +
586
- suffix
587
- );
657
+ return `GitHub GraphQL preflight did not refuse this session (verdict=${verdict ?? 'unknown'}).${suffix}`;
588
658
  }
589
659
 
590
660
  export default exec;