mandrel 2.91.0 → 2.92.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.
@@ -113,7 +113,10 @@ export async function finishWithMergeWait(prCtx, deps) {
113
113
  injectedNotify: deps.injectedNotify,
114
114
  runPostLandTailFn: (args) => {
115
115
  deps.setPhase('post-land');
116
- return runPostLandTail(args);
116
+ return runPostLandTail({
117
+ ...args,
118
+ releaseStoryLeaseFn: deps.releaseLease,
119
+ });
117
120
  },
118
121
  });
119
122
  const terminal = terminalFromWaitOutcome({
@@ -51,35 +51,9 @@ import { discardHeldReview } from './review-overlap.js';
51
51
 
52
52
  const progress = Logger.createProgress('single-story-close', { stderr: true });
53
53
 
54
- async function releaseLease({ storyId }, deps) {
55
- try {
56
- const outcome = await deps.releaseLease({
57
- provider: deps.provider,
58
- storyId,
59
- config: deps.config,
60
- });
61
- progress(
62
- 'LEASE',
63
- outcome.released
64
- ? `🔓 Story #${storyId} lease released.`
65
- : `🔓 Story #${storyId} lease not released (${outcome.reason}).`,
66
- );
67
- return outcome.released;
68
- } catch (err) {
69
- progress(
70
- 'LEASE',
71
- `⚠️ lease release failed (close continues): ${err?.message ?? err}`,
72
- );
73
- return false;
74
- }
75
- }
76
-
77
54
  /**
78
- * Re-take the Story lease before any gate, push or PR write: a block released
79
- * it, and init is the only other acquirer, so a re-close would otherwise run
80
- * unassigned and unguarded. No steal — a foreign holder throws init's
81
- * refusal. No configured operator handle skips the acquire (release is
82
- * best-effort for the same reason), so close never newly hard-fails on it.
55
+ * Re-affirm the Story lease before any write; normally `already-held`, since
56
+ * only the post-land tail releases it. No steal; no operator handle skips it.
83
57
  */
84
58
  async function acquireLease({ storyId }, deps) {
85
59
  const operator = resolveOperatorFromCandidates({
@@ -105,24 +79,6 @@ async function acquireLease({ storyId }, deps) {
105
79
  return lease;
106
80
  }
107
81
 
108
- /**
109
- * Release the lease best-effort before re-throwing a blocked-prone phase's
110
- * error verbatim. The lease has no TTL, so a stranded claim would refuse the
111
- * next operator who picks up the blocked Story.
112
- *
113
- * @template T
114
- * @param {() => Promise<T>} run
115
- * @returns {Promise<T>}
116
- */
117
- async function releaseLeaseOnBlock(run, ctx, deps) {
118
- try {
119
- return await run();
120
- } catch (err) {
121
- await releaseLease(ctx, deps);
122
- throw err;
123
- }
124
- }
125
-
126
82
  /**
127
83
  * Tests mock these at their module URLs and re-import only this module, so
128
84
  * they are bound here and handed to the phases rather than imported there.
@@ -161,6 +117,21 @@ function resolveCloseDeps(options, injected) {
161
117
  };
162
118
  }
163
119
 
120
+ function assertStoryId(options) {
121
+ if (!options.storyId) {
122
+ throw new Error(
123
+ 'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>] [--worker-tokens <n>] [--worker-model <model>] [--worker-effort <level>]',
124
+ );
125
+ }
126
+ }
127
+
128
+ function tagCloseError(err, { phaseTimer, phase, observedGates }) {
129
+ if (!err || typeof err !== 'object') return;
130
+ err.closePhaseDurations = phaseTimer.finish();
131
+ if (!err.closePhase) err.closePhase = phase;
132
+ if (!err.closeGates && observedGates) err.closeGates = observedGates;
133
+ }
134
+
164
135
  export async function runSingleStoryClose({
165
136
  storyId: storyIdParam,
166
137
  cwd: cwdParam,
@@ -194,11 +165,7 @@ export async function runSingleStoryClose({
194
165
  workerModelParam,
195
166
  workerEffortParam,
196
167
  });
197
- if (!options.storyId) {
198
- throw new Error(
199
- 'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>] [--worker-tokens <n>] [--worker-model <model>] [--worker-effort <level>]',
200
- );
201
- }
168
+ assertStoryId(options);
202
169
 
203
170
  // The runner keeps THROWING; it only tags the error with its phase and the
204
171
  // gates it observed (null until validation reports), and the CLI boundary
@@ -236,11 +203,7 @@ export async function runSingleStoryClose({
236
203
  deps,
237
204
  );
238
205
  } catch (err) {
239
- if (err && typeof err === 'object') {
240
- err.closePhaseDurations = phaseTimer.finish();
241
- if (!err.closePhase) err.closePhase = phase;
242
- if (!err.closeGates && observedGates) err.closeGates = observedGates;
243
- }
206
+ tagCloseError(err, { phaseTimer, phase, observedGates });
244
207
  throw err;
245
208
  }
246
209
  }
@@ -271,7 +234,6 @@ async function graphqlPreflightPhase(ctx, deps) {
271
234
  probe: deps.graphqlProbe,
272
235
  });
273
236
  if (!preflight) return null;
274
- await releaseLease(ctx, deps);
275
237
  return await preflightBlockedResult({
276
238
  storyId: ctx.storyId,
277
239
  preflight,
@@ -396,11 +358,7 @@ function landedPr(ctx) {
396
358
  }
397
359
 
398
360
  async function prePushPhase(ctx, deps) {
399
- ctx.prePush = await releaseLeaseOnBlock(
400
- () => runPrePushPhases(ctx, deps),
401
- ctx,
402
- deps,
403
- );
361
+ ctx.prePush = await runPrePushPhases(ctx, deps);
404
362
  if (!ctx.prePush.pending) return null;
405
363
  discardHeldReview(ctx.heldReview, 'validation pending', progress);
406
364
  return await finishDeferred(ctx.prePush.lockWait, {
@@ -415,11 +373,7 @@ async function prePushPhase(ctx, deps) {
415
373
  }
416
374
 
417
375
  async function openPrPhase(ctx, deps) {
418
- ctx.pr = await releaseLeaseOnBlock(
419
- () => openAndReviewPr(ctx, deps),
420
- ctx,
421
- deps,
422
- );
376
+ ctx.pr = await openAndReviewPr(ctx, deps);
423
377
  return null;
424
378
  }
425
379
 
@@ -460,22 +414,9 @@ async function armPhase(ctx, deps) {
460
414
  return null;
461
415
  }
462
416
 
463
- /** Wait-for-merge needs the arm outcome, so it is resolved here. */
464
- async function finishPhase(ctx, deps) {
417
+ function buildPrContext(ctx, deps) {
465
418
  const { options, arm } = ctx;
466
- const { waitForMerge, reason: waitForMergeReason } = resolveWaitForMerge({
467
- waitForMergeExplicit: options.waitForMergeExplicit,
468
- noWaitForMerge: options.noWaitForMerge,
469
- config: deps.config,
470
- autoMergeReason: arm.autoMergeReason,
471
- });
472
- reportOperatorMergeSkip({
473
- waitForMergeReason,
474
- autoMergeReason: arm.autoMergeReason,
475
- storyId: ctx.storyId,
476
- waitForMergeExplicit: options.waitForMergeExplicit,
477
- });
478
- const prCtx = {
419
+ return {
479
420
  storyId: ctx.storyId,
480
421
  storyBranch: ctx.storyBranch,
481
422
  baseBranch: ctx.baseBranch,
@@ -500,8 +441,32 @@ async function finishPhase(ctx, deps) {
500
441
  ctx.pr.reviewDegraded,
501
442
  ),
502
443
  };
444
+ }
445
+
446
+ function decideWaitForMerge(ctx, deps) {
447
+ const { options, arm } = ctx;
448
+ const decision = resolveWaitForMerge({
449
+ waitForMergeExplicit: options.waitForMergeExplicit,
450
+ noWaitForMerge: options.noWaitForMerge,
451
+ config: deps.config,
452
+ autoMergeReason: arm.autoMergeReason,
453
+ });
454
+ reportOperatorMergeSkip({
455
+ waitForMergeReason: decision.reason,
456
+ autoMergeReason: arm.autoMergeReason,
457
+ storyId: ctx.storyId,
458
+ waitForMergeExplicit: options.waitForMergeExplicit,
459
+ });
460
+ return decision;
461
+ }
462
+
463
+ /** Wait-for-merge needs the arm outcome, so it is resolved here. */
464
+ async function finishPhase(ctx, deps) {
465
+ const { options } = ctx;
466
+ const { waitForMerge, reason } = decideWaitForMerge(ctx, deps);
467
+ const prCtx = buildPrContext(ctx, deps);
503
468
  if (!waitForMerge) {
504
- return await finishWithoutMergeWait(prCtx, waitForMergeReason);
469
+ return await finishWithoutMergeWait(prCtx, reason);
505
470
  }
506
471
  return await finishWithMergeWait(prCtx, {
507
472
  cwd: options.cwd,
@@ -513,6 +478,7 @@ async function finishPhase(ctx, deps) {
513
478
  injectedGh: deps.gh,
514
479
  injectedNotify: deps.notify,
515
480
  runConfirmMergePhase: deps.runConfirmMergePhase,
481
+ releaseLease: deps.releaseLease,
516
482
  });
517
483
  }
518
484
 
@@ -25,6 +25,7 @@ const INSTALL_FLAGS = Object.freeze({ installed: 'true', failed: 'false' });
25
25
  * @param {boolean} args.dryRun
26
26
  * @param {{ remoteVerified: boolean, remoteUrl?: string, detail?: string }} args.remote
27
27
  * @param {string|null} args.checklistPath
28
+ * @param {{ status: string, reason?: string }|null} [args.boardSync]
28
29
  * @returns {{ result: object, summary: object }}
29
30
  */
30
31
  export function composeStoryInitResult({
@@ -41,6 +42,7 @@ export function composeStoryInitResult({
41
42
  dryRun,
42
43
  remote,
43
44
  checklistPath,
45
+ boardSync = null,
44
46
  }) {
45
47
  const dependenciesInstalled =
46
48
  INSTALL_FLAGS[installStatus.status] ?? 'skipped';
@@ -68,6 +70,7 @@ export function composeStoryInitResult({
68
70
  // Footprint-matched write-time checklist (null when no lens matches) —
69
71
  // the same Story-scoped path a multi-Story dispatch prompt names.
70
72
  checklistPath,
73
+ boardSync,
71
74
  };
72
75
  const summary = {
73
76
  storyId,
@@ -78,6 +81,14 @@ export function composeStoryInitResult({
78
81
  remoteVerified: remote.remoteVerified,
79
82
  checklistPath,
80
83
  dryRun,
84
+ boardSync: summarizeBoardSync(boardSync),
81
85
  };
82
86
  return { result, summary };
83
87
  }
88
+
89
+ /** The status, plus its reason when the board did not move. */
90
+ function summarizeBoardSync(boardSync) {
91
+ if (!boardSync) return null;
92
+ if (!boardSync.reason) return boardSync.status;
93
+ return `${boardSync.status} (${boardSync.reason})`;
94
+ }
@@ -106,15 +106,49 @@ async function loadTicketSnapshot(provider, opts, ticketId, needFromState) {
106
106
  }
107
107
  }
108
108
 
109
+ const BOARD_SYNC_REMEDIES = Object.freeze({
110
+ 'insufficient-scope': 'gh auth refresh -h github.com -s project',
111
+ 'not-on-project': 'node .agents/scripts/board-backfill.js',
112
+ });
113
+
114
+ const SILENT_BOARD_SKIPS = new Set(['no-project']);
115
+
116
+ /** Warns on every flip, never latched: agents read the flip's own output. */
117
+ function reportBoardSync(ticketId, newState, boardSync) {
118
+ if (boardSync.status === 'synced') return;
119
+ if (SILENT_BOARD_SKIPS.has(boardSync.reason)) return;
120
+ Logger.warn(boardSyncMessage(ticketId, newState, boardSync));
121
+ }
122
+
123
+ function boardSyncMessage(ticketId, newState, { status, reason, detail }) {
124
+ const why = detail ? `${reason}: ${detail}` : reason;
125
+ const remedy = BOARD_SYNC_REMEDIES[reason];
126
+ const fix = remedy ? ` — fix: \`${remedy}\`` : '';
127
+ return `[Ticketing] board Status not synced for #${ticketId} → ${newState} (${status}, ${why})${fix}`;
128
+ }
129
+
130
+ /** First instance per provider wins, so a later `config` is ignored. */
131
+ function columnSyncFor(provider, _makeColumnSync, config) {
132
+ if (_makeColumnSync) return _makeColumnSync({ provider, logger: Logger });
133
+ if (!_columnSyncRegistry.has(provider)) {
134
+ _columnSyncRegistry.set(
135
+ provider,
136
+ new ColumnSync({ provider, logger: Logger, config }),
137
+ );
138
+ }
139
+ return _columnSyncRegistry.get(provider);
140
+ }
141
+
109
142
  /**
110
143
  * Mirror the new state onto the Projects v2 Status column. Best-effort: a
111
- * board failure is logged and never blocks the label transition. An injected
112
- * `_makeColumnSync` bypasses the registry so test stubs are never cached.
144
+ * board failure never blocks the label transition; the outcome is returned.
145
+ * An injected `_makeColumnSync` bypasses the registry.
113
146
  *
114
147
  * @param {object} provider
115
148
  * @param {number} ticketId
116
149
  * @param {string} newState
117
150
  * @param {(opts: object) => { sync: (id: number, labels: string[]) => Promise<object> }} [_makeColumnSync]
151
+ * @returns {Promise<{ status: string, reason?: string, column?: string, detail?: string }>}
118
152
  */
119
153
  async function syncProjectStatusColumn(
120
154
  provider,
@@ -124,25 +158,14 @@ async function syncProjectStatusColumn(
124
158
  config,
125
159
  ) {
126
160
  try {
127
- let sync;
128
- if (_makeColumnSync) {
129
- sync = _makeColumnSync({ provider, logger: Logger });
130
- } else {
131
- // `config` is read at construction only; the first instance per
132
- // provider wins, so a later transition's config is ignored.
133
- if (!_columnSyncRegistry.has(provider)) {
134
- _columnSyncRegistry.set(
135
- provider,
136
- new ColumnSync({ provider, logger: Logger, config }),
137
- );
138
- }
139
- sync = _columnSyncRegistry.get(provider);
140
- }
141
- await sync.sync(ticketId, [newState]);
161
+ const sync = columnSyncFor(provider, _makeColumnSync, config);
162
+ return await sync.sync(ticketId, [newState]);
142
163
  } catch (err) {
143
- Logger.warn(
144
- `[Ticketing] column sync failed for #${ticketId} → ${newState}: ${err?.message ?? err}`,
145
- );
164
+ return {
165
+ status: 'failed',
166
+ reason: 'error',
167
+ detail: String(err?.message ?? err),
168
+ };
146
169
  }
147
170
  }
148
171
 
@@ -250,6 +273,7 @@ async function emitBlockedFriction(ticketId, fromState, newState, opts) {
250
273
  * `cascade: false` suppresses the upward parent cascade.
251
274
  * `ticketSnapshot` is a pre-fetched ticket that saves the `fromState` read
252
275
  * and the provider's label-merge read. `_makeColumnSync` is a test seam.
276
+ * @returns {Promise<{ boardSync: { status: string, reason?: string, column?: string, detail?: string } }>}
253
277
  */
254
278
  export async function transitionTicketState(
255
279
  provider,
@@ -285,13 +309,14 @@ export async function transitionTicketState(
285
309
 
286
310
  await emitBlockedFriction(ticketId, fromState, newState, opts);
287
311
 
288
- await syncProjectStatusColumn(
312
+ const boardSync = await syncProjectStatusColumn(
289
313
  provider,
290
314
  ticketId,
291
315
  newState,
292
316
  opts._makeColumnSync,
293
317
  opts.config,
294
318
  );
319
+ reportBoardSync(ticketId, newState, boardSync);
295
320
 
296
321
  // Every transition re-derives parent state from children (not just `done`),
297
322
  // keeping the board accurate when work starts or a child blocks.
@@ -310,6 +335,7 @@ export async function transitionTicketState(
310
335
  newState,
311
336
  });
312
337
  }
338
+ return { boardSync };
313
339
  }
314
340
 
315
341
  /**
@@ -143,25 +143,27 @@ export async function assertNotForeignExecuting({
143
143
  }
144
144
 
145
145
  /**
146
- * Best-effort: the lease is the real guard, so a failed flip only logs.
147
- *
148
- * @param {object} provider
149
- * @param {number} storyId
150
- * @param {object} story Prefetched snapshot.
151
- * @returns {Promise<void>}
146
+ * A failed flip rolls the claim back and throws: a ready, assigned Story
147
+ * reads as a stalled dispatch. Returns the flip's board-sync outcome.
152
148
  */
153
- async function flipStoryToExecuting(provider, storyId, story) {
149
+ async function flipStoryToExecuting(provider, storyId, story, config) {
150
+ let flip;
154
151
  try {
155
- await transitionTicketState(provider, storyId, STATE_LABELS.EXECUTING, {
156
- ticketSnapshot: story,
157
- cascade: false,
158
- });
159
- progress('LABELS', `🏷️ Story #${storyId} → agent::executing`);
152
+ flip = await transitionTicketState(
153
+ provider,
154
+ storyId,
155
+ STATE_LABELS.EXECUTING,
156
+ { ticketSnapshot: story, cascade: false, config },
157
+ );
160
158
  } catch (err) {
161
159
  Logger.error(
162
- `[single-story-init] ⚠️ Failed to flip Story labels: ${err?.message ?? err}`,
160
+ `[single-story-init] ⚠️ Failed to flip Story #${storyId} to agent::executing; rolling the claim back: ${err?.message ?? err}`,
163
161
  );
162
+ await rollbackClaimOnInitFailure(provider, storyId, config);
163
+ throw err;
164
164
  }
165
+ progress('LABELS', `🏷️ Story #${storyId} → agent::executing`);
166
+ return flip?.boardSync ?? null;
165
167
  }
166
168
 
167
169
  /**
@@ -647,6 +649,7 @@ export async function runSingleStoryInit({
647
649
  let worktreeCreated = false;
648
650
  let installStatus = { status: 'skipped', reason: 'dry-run' };
649
651
  let worktreeSweep = null;
652
+ let boardSync = null;
650
653
 
651
654
  if (!dryRun) {
652
655
  const acquire = injectedAcquireLease ?? acquireStoryLease;
@@ -671,7 +674,7 @@ export async function runSingleStoryInit({
671
674
  });
672
675
 
673
676
  // Before the install, so a concurrent probe cannot double-dispatch.
674
- await flipStoryToExecuting(provider, storyId, story);
677
+ boardSync = await flipStoryToExecuting(provider, storyId, story, config);
675
678
 
676
679
  // After the flip (the rollup reads it), before the install window.
677
680
  await rollUpContainerEpic(provider, storyId, config);
@@ -723,6 +726,7 @@ export async function runSingleStoryInit({
723
726
  dryRun,
724
727
  remote,
725
728
  checklistPath,
729
+ boardSync,
726
730
  });
727
731
 
728
732
  // The envelope (stdout + disk) is the only record; no ticket comment. Full
@@ -36,8 +36,15 @@ foreign claim is stale — a foreign assignee is treated as a _live_ claim:
36
36
  the current owner. Coordinate with that operator, or pass **`--steal`** to
37
37
  forcibly transfer the claim once you have confirmed the other run is dead.
38
38
 
39
- `--dry-run` skips the lease (no assignee mutation). The matching release
40
- runs in `single-story-close.js` (Step 3).
39
+ `--dry-run` skips the lease (no assignee mutation). The claim lives for the
40
+ Story's whole delivery: it is released only by close's post-land tail once
41
+ the merge is confirmed (Step 3), or by init's own rollback when provisioning
42
+ fails or the `agent::executing` flip does not land — that flip is not
43
+ best-effort, so init exits non-zero rather than leave a ready Story assigned.
44
+ A blocked or failed close **keeps** the claim. The flip's Projects v2 outcome
45
+ is reported as `boardSync` in the init envelope; a Status that did not move
46
+ logs one warning naming the fix (`gh auth refresh -h github.com -s project`
47
+ for a token without the `project` scope).
41
48
 
42
49
  ### Branch reuse
43
50
 
@@ -339,12 +346,16 @@ The `single-story-close.js` script, in order:
339
346
  `blocked` or `failed` close keeps its working copy. A missing worktree is
340
347
  recreated from `story-<id>` before close's first git operation — and the
341
348
  `--wait` resume's — never falling back to the main checkout.
342
- 7. **Releases the Story lease** — a no-op when the operator no longer holds
343
- the claim, so a late close never yanks a live claim. Best-effort: a
344
- release failure is logged, not fatal, and reported as
345
- `leaseReleased: <boolean>`. The fail-closed lease never expires on its
346
- own, so a claim stranded by a failed release is cleared only by `--steal`
347
- or by de-assigning the ticket.
349
+ 7. **Releases the Story lease only after the merge is confirmed** — the
350
+ post-land tail's step, a no-op when the operator no longer holds the
351
+ claim, so a late close never yanks a live claim. Every other ending keeps
352
+ it: a red gate, a review-critical halt, a base-sync conflict, a blocked
353
+ GraphQL preflight, `pending` and `blocked` all leave the Story assigned,
354
+ because its label still says it is owned; the next close re-affirms the
355
+ claim as `already-held`. Best-effort: a release failure is logged, not
356
+ fatal, and reported as `leaseReleased: <boolean>`. The fail-closed lease
357
+ never expires on its own, so a claim stranded by a failed release is
358
+ cleared only by `--steal` or by de-assigning the ticket.
348
359
 
349
360
  The merge wait recovers on its own when `main` moves under the queued PR. A
350
361
  `DIRTY` PR is merged with `origin/<base>` in the Story worktree in that same
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,13 @@ 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.92.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.91.0...mandrel-v2.92.0) (2026-10-18)
19
+
20
+
21
+ ### Fixed
22
+
23
+ * keep the Story assignee until the merge lands, and report every board-Status sync that did not happen ([#5784](https://github.com/dsj1984/mandrel/issues/5784)) ([#5785](https://github.com/dsj1984/mandrel/issues/5785)) ([8ca2b61](https://github.com/dsj1984/mandrel/commit/8ca2b611adb70a4bb53ec3b35dcdfe42dc1528bc))
24
+
18
25
  ## [2.91.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.90.0...mandrel-v2.91.0) (2026-10-18)
19
26
 
20
27
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.91.0",
3
+ "version": "2.92.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/",