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
@@ -1,13 +1,15 @@
1
1
  /**
2
- * phases/graphql-preflight.js — refuse the close during `init` when GitHub
3
- * GraphQL (which all of `gh pr` needs) is unreachable, before any gate runs
4
- * or anything is pushed. It must never fail a healthy close: ambiguous or
5
- * throwing probes are fail-open.
2
+ * phases/graphql-preflight.js — pick the close's PR transport during `init`,
3
+ * before any gate runs or anything is pushed. GraphQL unreachable (the proxy
4
+ * 403) seeds the `gh-exec` latch so every `gh pr` call goes over repo-scoped
5
+ * REST; only an auth fault, which REST would hit too, refuses the close. It
6
+ * must never fail a healthy close: ambiguous or throwing probes are fail-open.
6
7
  */
7
8
 
8
9
  import {
9
10
  describeGraphqlPreflight,
10
11
  probeGraphqlAvailability,
12
+ setGraphqlAvailability,
11
13
  } from '../../../gh-exec.js';
12
14
  import { Logger } from '../../../Logger.js';
13
15
  import {
@@ -31,8 +33,8 @@ async function announcePreflightBlock({ provider, storyId, reason, progress }) {
31
33
  reason,
32
34
  '',
33
35
  'Nothing was validated, committed, or pushed — the preflight runs before the',
34
- 'gate chain, so re-running close from a session that can reach GraphQL starts',
35
- 'from exactly where this Story stands now:',
36
+ 'gate chain, so re-running close once `gh` is authenticated starts from',
37
+ 'exactly where this Story stands now:',
36
38
  '',
37
39
  '```bash',
38
40
  `node .agents/scripts/single-story-close.js --story ${storyId}`,
@@ -56,6 +58,33 @@ async function announcePreflightBlock({ provider, storyId, reason, progress }) {
56
58
  }
57
59
  }
58
60
 
61
+ /** The probe's verdict, or `null` when the (injected) probe threw. */
62
+ async function readVerdict({ probe, ghFacade, progress }) {
63
+ try {
64
+ return await probe(ghFacade ? { ghFacade } : undefined);
65
+ } catch (err) {
66
+ progress(
67
+ 'PREFLIGHT',
68
+ `⚠️ GraphQL preflight could not run (close continues): ${err?.message ?? err}`,
69
+ );
70
+ return null;
71
+ }
72
+ }
73
+
74
+ /** The line a proceeding verdict prints, keyed by its transport. */
75
+ const PROCEED_LINES = Object.freeze({
76
+ graphql: (verdict) => `✅ GitHub GraphQL reachable (${verdict?.reason}).`,
77
+ rest: () =>
78
+ '↪ GitHub GraphQL is unavailable in this session (HTTP 403) — the pull-request ' +
79
+ 'surface runs over repo-scoped REST for this close.',
80
+ });
81
+
82
+ /** @returns {'graphql'|'rest'|null} the transport to proceed on, or null to refuse. */
83
+ function proceedingTransport(verdict) {
84
+ if (verdict?.available !== false) return 'graphql';
85
+ return verdict.verdict === 'unavailable' ? 'rest' : null;
86
+ }
87
+
59
88
  /**
60
89
  * A throwing (injected) probe is treated as available.
61
90
  *
@@ -75,18 +104,12 @@ export async function runGraphqlPreflight({
75
104
  ghFacade,
76
105
  probe = probeGraphqlAvailability,
77
106
  }) {
78
- let verdict;
79
- try {
80
- verdict = await probe(ghFacade ? { ghFacade } : undefined);
81
- } catch (err) {
82
- progress(
83
- 'PREFLIGHT',
84
- `⚠️ GraphQL preflight could not run (close continues): ${err?.message ?? err}`,
85
- );
86
- return null;
87
- }
88
- if (verdict?.available !== false) {
89
- progress('PREFLIGHT', `✅ GitHub GraphQL reachable (${verdict?.reason}).`);
107
+ const verdict = await readVerdict({ probe, ghFacade, progress });
108
+ if (verdict === null) return null;
109
+ setGraphqlAvailability(verdict ?? null);
110
+ const transport = proceedingTransport(verdict);
111
+ if (transport) {
112
+ progress('PREFLIGHT', PROCEED_LINES[transport](verdict));
90
113
  return null;
91
114
  }
92
115
  const reason = describeGraphqlPreflight(verdict);
@@ -111,7 +111,7 @@ const BOARD_SYNC_REMEDIES = Object.freeze({
111
111
  'not-on-project': 'node .agents/scripts/board-backfill.js',
112
112
  });
113
113
 
114
- const SILENT_BOARD_SKIPS = new Set(['no-project']);
114
+ const SILENT_BOARD_SKIPS = new Set(['no-project', 'graphql-blocked']);
115
115
 
116
116
  /** Warns on every flip, never latched: agents read the flip's own output. */
117
117
  function reportBoardSync(ticketId, newState, boardSync) {
@@ -4,11 +4,11 @@
4
4
  * be enabled via API. Never throws (issue creation survives a board failure)
5
5
  * and is idempotent (the mutation returns an existing item). A token without
6
6
  * the `project` scope reports `reason: 'insufficient-scope'` and trips the
7
- * warn-once latch rather than warning per issue.
7
+ * warn-once latch rather than warning per issue (`graphql-blocked` likewise).
8
8
  */
9
9
 
10
10
  import { Logger } from '../../lib/Logger.js';
11
- import { boardScopeFailure } from '../../lib/orchestration/board-access-latch.js';
11
+ import { boardAccessFailure } from '../../lib/orchestration/board-graphql-latch.js';
12
12
 
13
13
  /**
14
14
  * No project number → no-op without network.
@@ -38,7 +38,7 @@ export async function addIssueToBoard({
38
38
  await addItemToProject(nodeId);
39
39
  return { added: true };
40
40
  } catch (err) {
41
- const scopeFailure = boardScopeFailure(err);
41
+ const scopeFailure = boardAccessFailure(err);
42
42
  if (scopeFailure) return { added: false, ...scopeFailure };
43
43
  warnAddFailure(err, issueNumber, nodeId);
44
44
  return { added: false, reason: 'error' };
@@ -12,6 +12,7 @@ import { MergeMethodsGateway } from './merge-methods.js';
12
12
  import { ProjectBoardGateway } from './project-board.js';
13
13
  import * as projects from './projects-v2-graphql.js';
14
14
  import { SubIssueGateway } from './sub-issues.js';
15
+ import { createSubIssueRestFallback } from './sub-issues-rest.js';
15
16
  import { TicketGateway } from './tickets.js';
16
17
 
17
18
  /** Mutates `provider` in place. */
@@ -33,6 +34,7 @@ export function composeGateways(provider) {
33
34
  ghGraphql: (q, v, o) => p.graphql(q, v, o),
34
35
  cache: p._cache,
35
36
  classifyGithubError,
37
+ restFallback: createSubIssueRestFallback({ ...ghDeps, cache: p._cache }),
36
38
  });
37
39
  p.comments = new CommentGateway({
38
40
  ...ghDeps,
@@ -147,6 +147,47 @@ export function classifyGithubError(err) {
147
147
  return 'permanent';
148
148
  }
149
149
 
150
+ // The cloud proxy's own wording, so an ordinary 403 never matches.
151
+ const GRAPHQL_BLOCKED_RE =
152
+ /GitHub GraphQL is not available from Claude Code sessions/i;
153
+ const PROXY_SCOPE_REFUSAL_RE =
154
+ /is not enabled for this session|sessions are bound to their configured repositories/i;
155
+
156
+ const CAUSE_DEPTH = 3;
157
+
158
+ /**
159
+ * @param {unknown} err
160
+ * @returns {string}
161
+ */
162
+ function failureText(err) {
163
+ const parts = [];
164
+ let cur = err;
165
+ for (let depth = 0; cur && depth < CAUSE_DEPTH; depth++) {
166
+ parts.push(
167
+ stderrText(cur),
168
+ typeof cur.message === 'string' ? cur.message : '',
169
+ );
170
+ cur = cur.cause;
171
+ }
172
+ return parts.join(' ');
173
+ }
174
+
175
+ /**
176
+ * @param {unknown} err
177
+ * @returns {boolean}
178
+ */
179
+ export function isGraphqlBlocked(err) {
180
+ return GRAPHQL_BLOCKED_RE.test(failureText(err));
181
+ }
182
+
183
+ /**
184
+ * @param {unknown} err
185
+ * @returns {boolean}
186
+ */
187
+ export function isProxyScopeRefusal(err) {
188
+ return PROXY_SCOPE_REFUSAL_RE.test(failureText(err));
189
+ }
190
+
150
191
  export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
151
192
  maxAttempts: 6,
152
193
  baseDelayMs: 500,
@@ -0,0 +1,55 @@
1
+ /** GitHub Provider — REST sub-issues once a session's proxy refuses GraphQL. */
2
+
3
+ import { Logger } from '../../lib/Logger.js';
4
+ import { isGraphqlBlocked } from './errors.js';
5
+ import { issueToTicket } from './mappers.js';
6
+ import { paginateRest } from './request-helpers.js';
7
+
8
+ const PAGE_CAP = 50;
9
+ const PAGE_SIZE = 100;
10
+
11
+ const PROCESS_LATCH = { blocked: false };
12
+
13
+ /**
14
+ * @typedef {{
15
+ * latched: (parentId: number) => Promise<number[]> | null,
16
+ * onError: (err: unknown, parentId: number) => Promise<number[]> | null,
17
+ * }} SubIssueRestFallback
18
+ */
19
+
20
+ /**
21
+ * @param {{ gh: object, owner: string, repo: string, cache?: object }} deps
22
+ * @param {{ blocked: boolean }} [latch]
23
+ * @returns {SubIssueRestFallback}
24
+ */
25
+ export function createSubIssueRestFallback(deps, latch = PROCESS_LATCH) {
26
+ const list = (parentId) => listSubIssuesViaRest({ ...deps, parentId });
27
+ return {
28
+ latched: (parentId) => (latch.blocked ? list(parentId) : null),
29
+ onError(err, parentId) {
30
+ if (!isGraphqlBlocked(err)) return null;
31
+ if (!latch.blocked) {
32
+ Logger.warn(
33
+ '[GitHubProvider] GitHub GraphQL is refused in this session (Claude Code cloud proxy); ' +
34
+ 'reading sub-issues over REST for the rest of the run',
35
+ );
36
+ }
37
+ latch.blocked = true;
38
+ return list(parentId);
39
+ },
40
+ };
41
+ }
42
+
43
+ async function listSubIssuesViaRest({ gh, owner, repo, parentId, cache }) {
44
+ const rows = await paginateRest(
45
+ gh,
46
+ `/repos/${owner}/${repo}/issues/${parentId}/sub_issues`,
47
+ {
48
+ pageCap: PAGE_CAP,
49
+ perPage: PAGE_SIZE,
50
+ label: `getNativeSubIssues(rest) parent=#${parentId}`,
51
+ },
52
+ );
53
+ for (const row of rows) cache?.primeIfAbsent?.(issueToTicket(row));
54
+ return rows.map((row) => row.number);
55
+ }
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * GitHub Provider — SubIssueGateway: the read side of native Sub-Issues (the
3
3
  * GraphQL `subIssues` field, paginated into child numbers). Holds no
4
- * transport state; every call goes through the parent's `ghGraphql` hook.
4
+ * transport state; every call goes through the parent's `ghGraphql` hook
5
+ * (or `restFallback` once GraphQL is refused).
5
6
  */
6
7
 
7
8
  import { describeGhFailure } from '../../lib/gh-exec.js';
@@ -23,20 +24,25 @@ export class SubIssueGateway {
23
24
  * ghGraphql: (query: string, variables?: object, opts?: object) => Promise<object>,
24
25
  * cache?: { primeIfAbsent: (ticket: object) => void },
25
26
  * classifyGithubError?: (err: unknown) => string,
27
+ * restFallback?: object | null,
26
28
  * }} deps
27
29
  */
28
30
  constructor({
29
31
  ghGraphql,
30
32
  cache,
31
33
  classifyGithubError = defaultClassifyGithubError,
34
+ restFallback = null,
32
35
  } = {}) {
33
36
  this._ghGraphql = ghGraphql;
37
+ this._restFallback = restFallback;
34
38
  this._cache = cache;
35
39
  this._classify = classifyGithubError;
36
40
  }
37
41
 
38
42
  /** Primes the ticket cache; `[]` when the feature is disabled. */
39
43
  async getNativeSubIssues(parentNodeId, parentId) {
44
+ const latched = this._restFallback?.latched(parentId);
45
+ if (latched) return latched;
40
46
  const childIds = [];
41
47
  let cursor = null;
42
48
  try {
@@ -72,6 +78,8 @@ export class SubIssueGateway {
72
78
  }
73
79
  }
74
80
  } catch (err) {
81
+ const rest = this._restFallback?.onError(err, parentId);
82
+ if (rest) return rest;
75
83
  const category = this._classify(err);
76
84
  if (category === 'feature-disabled') {
77
85
  Logger.warn(
@@ -303,6 +303,8 @@ async function resumeMergeWait(ctx) {
303
303
  cwd: ctx.cwd,
304
304
  resolveWorktree: lazyWaitWorktree(ctx),
305
305
  closeArmed: evidence.armed,
306
+ // `rest-merge-on-green` tells the wait it owns the merge.
307
+ autoMergeReason: evidence.reason,
306
308
  storyId,
307
309
  storyBranch,
308
310
  baseBranch,
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,18 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.94.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.93.0...mandrel-v2.94.0) (2026-10-20)
19
+
20
+
21
+ ### Added
22
+
23
+ * close, merge and confirm a Story over repo-scoped REST when GitHub GraphQL is blocked ([#5793](https://github.com/dsj1984/mandrel/issues/5793)) ([#5796](https://github.com/dsj1984/mandrel/issues/5796)) ([e2cd9ff](https://github.com/dsj1984/mandrel/commit/e2cd9ff1feaac25434674f919d4e8663c5ef6cfb))
24
+
25
+
26
+ ### Fixed
27
+
28
+ * plan-side GitHub reads work over REST in cloud sessions, and blocked GraphQL warns once, not once per item ([#5794](https://github.com/dsj1984/mandrel/issues/5794)) ([#5795](https://github.com/dsj1984/mandrel/issues/5795)) ([d1a4280](https://github.com/dsj1984/mandrel/commit/d1a42802497b82b523ab4c1878114c7e775eb3b6))
29
+
18
30
  ## [2.93.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.92.0...mandrel-v2.93.0) (2026-10-19)
19
31
 
20
32
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.93.0",
3
+ "version": "2.94.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",