mandrel 2.71.0 → 2.72.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.
- package/.agents/schemas/story-deliver-terminal.schema.json +10 -1
- package/.agents/scripts/lib/orchestration/cancelled-run-discount.js +129 -0
- package/.agents/scripts/lib/orchestration/deliver-recover.js +166 -34
- package/.agents/scripts/lib/orchestration/pr-watch.js +14 -3
- package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +45 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +13 -4
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +54 -6
- package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +296 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +52 -6
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +2 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/story-branch-catch-up.js +50 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js +64 -52
- package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-restore.js +133 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +161 -57
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +46 -6
- package/.agents/scripts/pr-watch-with-update.js +5 -0
- package/.agents/scripts/single-story-confirm-merge.js +34 -3
- package/.agents/workflows/helpers/deliver-story-reference.md +28 -9
- package/.agents/workflows/helpers/worktree-lifecycle.md +5 -5
- package/docs/CHANGELOG.md +12 -0
- package/package.json +1 -1
|
@@ -376,6 +376,7 @@ function buildWatchArgs({
|
|
|
376
376
|
ghPrChecksFn,
|
|
377
377
|
ghPrViewFn,
|
|
378
378
|
ghPrUpdateBranchFn,
|
|
379
|
+
ghApiFn,
|
|
379
380
|
sleepFn,
|
|
380
381
|
logger,
|
|
381
382
|
}) {
|
|
@@ -390,6 +391,7 @@ function buildWatchArgs({
|
|
|
390
391
|
...(ghPrChecksFn ? { ghPrChecksFn } : {}),
|
|
391
392
|
...(ghPrViewFn ? { ghPrViewFn } : {}),
|
|
392
393
|
...(ghPrUpdateBranchFn ? { ghPrUpdateBranchFn } : {}),
|
|
394
|
+
ghApiFn,
|
|
393
395
|
...(sleepFn ? { sleepFn } : {}),
|
|
394
396
|
logger,
|
|
395
397
|
};
|
|
@@ -605,6 +607,7 @@ async function settleRedWatch({
|
|
|
605
607
|
* @param {Function} [opts.ghPrChecksFn]
|
|
606
608
|
* @param {Function} [opts.ghPrViewFn]
|
|
607
609
|
* @param {Function} [opts.ghPrUpdateBranchFn]
|
|
610
|
+
* @param {Function} [opts.ghApiFn]
|
|
608
611
|
* @param {Function} [opts.sleepFn]
|
|
609
612
|
* @param {Function} [opts.writeDigestFn]
|
|
610
613
|
* @param {Function} [opts.readDigestFn]
|
|
@@ -630,6 +633,7 @@ export async function runPrWatch({
|
|
|
630
633
|
ghPrChecksFn,
|
|
631
634
|
ghPrViewFn,
|
|
632
635
|
ghPrUpdateBranchFn,
|
|
636
|
+
ghApiFn,
|
|
633
637
|
sleepFn,
|
|
634
638
|
writeDigestFn = writeCiDigest,
|
|
635
639
|
readDigestFn = readCiDigest,
|
|
@@ -676,6 +680,7 @@ export async function runPrWatch({
|
|
|
676
680
|
ghPrChecksFn,
|
|
677
681
|
ghPrViewFn,
|
|
678
682
|
ghPrUpdateBranchFn,
|
|
683
|
+
ghApiFn,
|
|
679
684
|
sleepFn,
|
|
680
685
|
logger,
|
|
681
686
|
}),
|
|
@@ -27,12 +27,15 @@ import { getStoryBranch } from './lib/git-utils.js';
|
|
|
27
27
|
import { Logger } from './lib/Logger.js';
|
|
28
28
|
import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
|
|
29
29
|
import { emitTerseResult } from './lib/observability/terse-result.js';
|
|
30
|
+
import { probeCloseArtifacts } from './lib/orchestration/deliver-recover.js';
|
|
30
31
|
import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
|
|
31
32
|
import { MERGE_WAIT_GH_TIMEOUT_MS } from './lib/orchestration/merge-poll.js';
|
|
33
|
+
import { closeArmedPr } from './lib/orchestration/single-story-close/phases/auto-merge.js';
|
|
32
34
|
import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
|
|
33
35
|
import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
|
|
34
36
|
import { assertNoRetiredFlags } from './lib/orchestration/single-story-close/phases/options.js';
|
|
35
37
|
import { runPostLandTail } from './lib/orchestration/single-story-close/phases/post-land.js';
|
|
38
|
+
import { resolveStoryWorktree } from './lib/orchestration/single-story-close/phases/worktree-restore.js';
|
|
36
39
|
import {
|
|
37
40
|
buildTerminalEnvelope,
|
|
38
41
|
emitTerminalEnvelope,
|
|
@@ -268,22 +271,44 @@ async function confirmWithoutPr(ctx) {
|
|
|
268
271
|
);
|
|
269
272
|
}
|
|
270
273
|
|
|
274
|
+
/** Lazy: only a DIRTY sync needs the worktree, never confirming a merge. */
|
|
275
|
+
function lazyWaitWorktree({ cwd, config, storyId, storyBranch, ...ctx }) {
|
|
276
|
+
return () =>
|
|
277
|
+
ctx.resolveWorktreeFn({ cwd, config, storyId, storyBranch, progress });
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* What the last close recorded about the arm, off its persisted envelope.
|
|
282
|
+
* Only positive evidence that close armed the PR lets the wait re-arm it.
|
|
283
|
+
*
|
|
284
|
+
* @returns {{ armed: boolean, reason: string|null }}
|
|
285
|
+
*/
|
|
286
|
+
function readCloseArmEvidence({ storyId, config, readCloseEnvelopeFn }) {
|
|
287
|
+
const { envelope } = readCloseEnvelopeFn({ storyId, config });
|
|
288
|
+
const pr = envelope?.storyId === storyId ? envelope.pr : null;
|
|
289
|
+
return { armed: closeArmedPr(pr), reason: pr?.autoMergeReason ?? null };
|
|
290
|
+
}
|
|
291
|
+
|
|
271
292
|
/**
|
|
272
293
|
* `--wait` runs the SAME phase as close so the cumulative budget give-up
|
|
273
294
|
* (the only path to `merge.unlanded` / `agent::blocked`) is reachable from a
|
|
274
295
|
* resume. The budget is anchored at the PR's `createdAt`, so resuming does
|
|
275
|
-
* not restart the clock.
|
|
296
|
+
* not restart the clock. The Story worktree is resolved (and recreated when
|
|
297
|
+
* missing) exactly as close does, so a DIRTY PR syncs there.
|
|
276
298
|
*/
|
|
277
299
|
async function resumeMergeWait(ctx) {
|
|
278
300
|
const { storyId, storyBranch, baseBranch, prNumber } = ctx;
|
|
301
|
+
const evidence = readCloseArmEvidence(ctx);
|
|
279
302
|
const waitOutcome = await ctx.runConfirmMergePhaseFn({
|
|
280
303
|
cwd: ctx.cwd,
|
|
304
|
+
resolveWorktree: lazyWaitWorktree(ctx),
|
|
305
|
+
closeArmed: evidence.armed,
|
|
281
306
|
storyId,
|
|
282
307
|
storyBranch,
|
|
283
308
|
baseBranch,
|
|
284
309
|
prNumber,
|
|
285
310
|
prUrl: `${storyBranch} PR #${prNumber}`,
|
|
286
|
-
//
|
|
311
|
+
// Enters the wait; re-arming a disarmed PR needs `closeArmed` above.
|
|
287
312
|
autoMergeEnabled: true,
|
|
288
313
|
maxWaitSeconds: ctx.maxWaitSeconds,
|
|
289
314
|
provider: ctx.provider,
|
|
@@ -300,7 +325,9 @@ async function resumeMergeWait(ctx) {
|
|
|
300
325
|
baseBranch,
|
|
301
326
|
prNumber,
|
|
302
327
|
prUrl: null,
|
|
303
|
-
|
|
328
|
+
// Carried forward, so the next resume reads the same evidence.
|
|
329
|
+
autoMergeEnabled: evidence.armed,
|
|
330
|
+
autoMergeReason: evidence.reason,
|
|
304
331
|
// This CLI runs no close gates.
|
|
305
332
|
gates: undefined,
|
|
306
333
|
elapsedSeconds: elapsedSeconds(ctx),
|
|
@@ -382,6 +409,8 @@ export async function runConfirmMerge({
|
|
|
382
409
|
injectedNotify,
|
|
383
410
|
injectedReadPrMergeState,
|
|
384
411
|
runConfirmMergePhaseFn = defaultRunConfirmMergePhase,
|
|
412
|
+
resolveWorktreeFn = resolveStoryWorktree,
|
|
413
|
+
readCloseEnvelopeFn = probeCloseArtifacts,
|
|
385
414
|
} = {}) {
|
|
386
415
|
if (!storyId) {
|
|
387
416
|
throw new Error(USAGE);
|
|
@@ -403,6 +432,8 @@ export async function runConfirmMerge({
|
|
|
403
432
|
injectedNotify,
|
|
404
433
|
injectedReadPrMergeState,
|
|
405
434
|
runConfirmMergePhaseFn,
|
|
435
|
+
resolveWorktreeFn,
|
|
436
|
+
readCloseEnvelopeFn,
|
|
406
437
|
};
|
|
407
438
|
|
|
408
439
|
progress('INIT', `Confirming merge for standalone Story #${storyId}...`);
|
|
@@ -326,8 +326,13 @@ The `single-story-close.js` script, in order:
|
|
|
326
326
|
would strand a CLOSED issue with no merged work if the PR failed CI, went
|
|
327
327
|
`BEHIND` base, or closed unmerged. A Story only reaches `agent::done` once
|
|
328
328
|
its PR to `main` is confirmed merged (Step 5).
|
|
329
|
-
6.
|
|
330
|
-
|
|
329
|
+
6. **Leaves the worktree in place.** Worktree lifetime is Story lifetime:
|
|
330
|
+
only the post-land tail reaps it (`tail.worktreeReap`, run before
|
|
331
|
+
`tail.refCleanup` because `git branch -D` refuses a branch a live
|
|
332
|
+
worktree holds; `reapOnSuccess: false` keeps it), so a `pending`,
|
|
333
|
+
`blocked` or `failed` close keeps its working copy. A missing worktree is
|
|
334
|
+
recreated from `story-<id>` before close's first git operation — and the
|
|
335
|
+
`--wait` resume's — never falling back to the main checkout.
|
|
331
336
|
7. **Releases the Story lease** — a no-op when the operator no longer holds
|
|
332
337
|
the claim, so a late close never yanks a live claim. Best-effort: a
|
|
333
338
|
release failure is logged, not fatal, and reported as
|
|
@@ -335,6 +340,18 @@ The `single-story-close.js` script, in order:
|
|
|
335
340
|
own, so a claim stranded by a failed release is cleared only by `--steal`
|
|
336
341
|
or by de-assigning the ticket.
|
|
337
342
|
|
|
343
|
+
The merge wait recovers on its own when `main` moves under the queued PR. A
|
|
344
|
+
`DIRTY` PR is merged with `origin/<base>` in the Story worktree in that same
|
|
345
|
+
poll (baseline-only conflicts auto-resolve), pushed with hooks, and the wait
|
|
346
|
+
continues — each sync spends one of the BEHIND update attempts. A conflict,
|
|
347
|
+
any other sync failure, or a spent budget posts `friction`, leaves the labels
|
|
348
|
+
alone, and ends `failed` at `phase: base-sync` naming the conflicted files
|
|
349
|
+
and the worktree: resolve there, commit, re-run close. The worktree is
|
|
350
|
+
resolved only for that sync, never to confirm a merge. A PR a new head
|
|
351
|
+
disarmed is re-armed once per head SHA, only when close armed it (the close
|
|
352
|
+
itself, or its persisted envelope) — never a `--no-auto-merge` or `strict`
|
|
353
|
+
PR, and not when the CI digest recorded a red against that head.
|
|
354
|
+
|
|
338
355
|
---
|
|
339
356
|
|
|
340
357
|
## Step 4 — CI watch + fix recovery
|
|
@@ -438,15 +455,17 @@ or an unrecoverable failure (→ `status: "failed"`) ends the turn — or a
|
|
|
438
455
|
genuine `pending` (§ Step 7). The statuses are the shipped
|
|
439
456
|
[terminal schema](../../schemas/story-deliver-terminal.schema.json)'s.
|
|
440
457
|
|
|
441
|
-
###
|
|
458
|
+
### A missing Story worktree
|
|
442
459
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
460
|
+
The worktree survives until the land, so a red PR's worktree is normally
|
|
461
|
+
still at `.worktrees/story-<storyId>/`. When it is gone, re-running close (or
|
|
462
|
+
the `--wait` resume) recreates it from `story-<storyId>`, fetching the ref
|
|
463
|
+
from origin when only the remote copy is left. To fix CI by hand first:
|
|
446
464
|
|
|
447
465
|
```bash
|
|
448
466
|
cd <main-repo>
|
|
449
|
-
git fetch origin story-<storyId>
|
|
467
|
+
git fetch origin story-<storyId>:story-<storyId>
|
|
468
|
+
git worktree prune # a deleted-but-registered entry blocks the add
|
|
450
469
|
git worktree add .worktrees/story-<storyId> story-<storyId>
|
|
451
470
|
cd .worktrees/story-<storyId>
|
|
452
471
|
```
|
|
@@ -535,8 +554,8 @@ once per project to delete the conflicting bot workflows entirely.
|
|
|
535
554
|
|
|
536
555
|
## Step 6 — Local branch cleanup detail
|
|
537
556
|
|
|
538
|
-
> **The land tail already ran this** — it is `tail.
|
|
539
|
-
> `tail.baseFastForward` in the terminal envelope. Run it by hand only when
|
|
557
|
+
> **The land tail already ran this** — it is `tail.worktreeReap`,
|
|
558
|
+
> `tail.refCleanup` and `tail.baseFastForward` in the terminal envelope. Run it by hand only when
|
|
540
559
|
> either step reported `false` (a dirty shared checkout is the common, benign
|
|
541
560
|
> cause), or after a manual merge on a `--no-wait-merge` run:
|
|
542
561
|
|
|
@@ -50,9 +50,9 @@ root, and shell-metacharacter injection in `root`.
|
|
|
50
50
|
| **Sweep** | Operator-driven (`WorktreeManager.sweepStaleLocks`) | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC. |
|
|
51
51
|
| **GC** | Operator-driven (`WorktreeManager.gc`) | Orphan `.worktrees/story-*` whose Stories are closed are reaped if clean. |
|
|
52
52
|
| **Force-drain** | Operator-driven (`drain-pending-cleanup.js`) | Retries `.worktrees/.pending-cleanup.json` (`git worktree remove` then `fs.rm`); Windows-only escalation enumerates user-mode handle holders and `taskkill`s them before re-trying. |
|
|
53
|
-
| **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`)
|
|
53
|
+
| **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`); close and the `--wait` resume when it is missing | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch (fetched from origin when no local ref remains). |
|
|
54
54
|
| **Run** | During Story execution | Agent runs inside the worktree; HEAD/reflog activity is isolated. |
|
|
55
|
-
| **Reap** | After
|
|
55
|
+
| **Reap** | After a confirmed merge, in the post-land tail (`tail.worktreeReap`) | `git worktree remove`, before the local ref reap — refuses a dirty tree. A `pending`, `blocked` or `failed` close keeps the worktree. |
|
|
56
56
|
|
|
57
57
|
The `WorktreeManager` (`.agents/scripts/lib/worktree-manager.js`) is the single
|
|
58
58
|
authority for `ensure`, `reap`, `list`, `isSafeToRemove`, `gc`, `prune`, and
|
|
@@ -86,7 +86,7 @@ epic-runner. The lifecycle surfaces that do run automatically are:
|
|
|
86
86
|
| Entry point | Script / caller | What it cleans |
|
|
87
87
|
| --------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
88
88
|
| Story init (`/mandrel-deliver <storyId>`) | `single-story-init.js` boot sweep (`sweepMergedStoryBranches`) | Merged/closed `story-*` branches (local + origin) from prior runs; it then creates only its own worktree. |
|
|
89
|
-
| Story close
|
|
89
|
+
| Story land (close's wait, or `--wait`) | The post-land tail's worktree-reap step (`WorktreeManager.reap`) | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`. |
|
|
90
90
|
| Drain pending-cleanup (operator) | `drain-pending-cleanup.js` (run directly — see below) | The pending-cleanup ledger, with optional Windows handle-holder escalation. This is the only path that drains the ledger. |
|
|
91
91
|
|
|
92
92
|
Operator takeaway: if worktrees or stale locks accumulate, run
|
|
@@ -95,8 +95,8 @@ Operator takeaway: if worktrees or stale locks accumulate, run
|
|
|
95
95
|
|
|
96
96
|
## Draining the pending-cleanup ledger
|
|
97
97
|
|
|
98
|
-
`.worktrees/.pending-cleanup.json` accumulates entries when
|
|
99
|
-
|
|
98
|
+
`.worktrees/.pending-cleanup.json` accumulates entries when the
|
|
99
|
+
post-land tail cannot remove a worktree on Windows because of
|
|
100
100
|
an EBUSY-class lock. If the holder is a long-lived user-mode process (a
|
|
101
101
|
stranded test runner, a lingering biome/tsc, a node REPL), the lock
|
|
102
102
|
never clears and the entry pins.
|
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.72.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.71.0...mandrel-v2.72.0) (2026-10-01)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* close keeps the worktree until land, self-syncs a DIRTY PR, re-arms a disarmed PR, and recover names both ([#5533](https://github.com/dsj1984/mandrel/issues/5533)) ([#5537](https://github.com/dsj1984/mandrel/issues/5537)) ([5e0fd9c](https://github.com/dsj1984/mandrel/commit/5e0fd9c8e2bcc7984188db291f20d3171c234c69))
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
### Fixed
|
|
27
|
+
|
|
28
|
+
* pr-watch ignores a required check from a concurrency-cancelled run while a live run on the same head exists ([#5534](https://github.com/dsj1984/mandrel/issues/5534)) ([#5535](https://github.com/dsj1984/mandrel/issues/5535)) ([caa2d6a](https://github.com/dsj1984/mandrel/commit/caa2d6ab935dd70d2ba40b3b8e952e4587a1ef1e))
|
|
29
|
+
|
|
18
30
|
## [2.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.70.0...mandrel-v2.71.0) (2026-09-30)
|
|
19
31
|
|
|
20
32
|
|
package/package.json
CHANGED