mandrel 2.74.0 → 2.75.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/docs/runbooks/mods.md +78 -16
- package/.agents/mods/mandrel-status/hooks/register.tsx +942 -108
- package/.agents/mods/mandrel-status/types/index.d.ts +67 -11
- package/.agents/schemas/story-progress.schema.json +48 -0
- package/.agents/scripts/lib/config/temp-paths.js +15 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +24 -3
- package/.agents/scripts/lib/orchestration/story-handoff.js +7 -0
- package/.agents/scripts/lib/orchestration/story-progress.js +127 -0
- package/docs/CHANGELOG.md +8 -0
- package/package.json +1 -1
|
@@ -1,24 +1,77 @@
|
|
|
1
|
-
/**
|
|
2
|
-
export type
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
1
|
+
/** The six stages of a /mandrel-deliver Story, in order. */
|
|
2
|
+
export type StageName =
|
|
3
|
+
| 'start'
|
|
4
|
+
| 'build'
|
|
5
|
+
| 'check'
|
|
6
|
+
| 'handoff'
|
|
7
|
+
| 'close'
|
|
8
|
+
| 'merge';
|
|
9
|
+
|
|
10
|
+
/** One stage as the Details pane lists it; times in epoch milliseconds. */
|
|
11
|
+
export type StageRow = {
|
|
12
|
+
name: StageName;
|
|
13
|
+
startedAt: number | null;
|
|
14
|
+
/** The next stage's start, or null while this one is current or pending. */
|
|
15
|
+
endedAt: number | null;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
/** One close phase: its recorded duration and the learned median, in seconds. */
|
|
19
|
+
export type PhaseRow = {
|
|
20
|
+
name: string;
|
|
21
|
+
seconds: number | null;
|
|
22
|
+
usualSeconds: number | null;
|
|
8
23
|
};
|
|
9
24
|
|
|
10
|
-
/** The
|
|
11
|
-
export type
|
|
25
|
+
/** The Story the band follows: in flight, or the newest recent result. */
|
|
26
|
+
export type Focus = {
|
|
12
27
|
storyId: number;
|
|
28
|
+
title: string | null;
|
|
29
|
+
/** `in-flight`, or the terminal envelope's `status`. */
|
|
13
30
|
status: string;
|
|
31
|
+
stage: StageName;
|
|
32
|
+
/** The current stage's step detail, already worded. */
|
|
33
|
+
detail: string;
|
|
34
|
+
stages: StageRow[];
|
|
35
|
+
handoffSteps: { name: string; at: number }[];
|
|
36
|
+
closePhases: PhaseRow[];
|
|
14
37
|
prNumber: number | null;
|
|
15
38
|
checksStatus: string | null;
|
|
39
|
+
/** The envelope's `elapsedSeconds`, for a finished result. */
|
|
16
40
|
elapsedSeconds: number | null;
|
|
41
|
+
/** Milliseconds into the current phase, while in flight. */
|
|
42
|
+
phaseElapsedMs: number | null;
|
|
43
|
+
/** The learned median of the current phase, once it has 3+ samples. */
|
|
44
|
+
usualMs: number | null;
|
|
45
|
+
isStalled: boolean;
|
|
46
|
+
/** Minutes the gate log has been quiet, when the 10-minute rule fired. */
|
|
47
|
+
idleMinutes: number | null;
|
|
48
|
+
/** `blocked.blockClass` or `failure.reason`. */
|
|
49
|
+
problem: string | null;
|
|
50
|
+
nextCommand: string | null;
|
|
51
|
+
/** Bullets in `follow-ups-rollup-<id>.md`, when it exists. */
|
|
52
|
+
followUps: number | null;
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
/** The newest live multi-Story run ledger. */
|
|
56
|
+
export type RunLine = {
|
|
57
|
+
landed: number;
|
|
58
|
+
total: number;
|
|
59
|
+
current: { storyId: number; stage: string } | null;
|
|
60
|
+
queued: number;
|
|
17
61
|
};
|
|
18
62
|
|
|
19
63
|
export type Snapshot = {
|
|
20
|
-
|
|
21
|
-
|
|
64
|
+
focus: Focus | null;
|
|
65
|
+
run: RunLine | null;
|
|
66
|
+
/** When the scan ran, epoch milliseconds; 0 before the first. */
|
|
67
|
+
scannedAt: number;
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
/** Per close phase: the median of the newest terminal envelopes' timings. */
|
|
71
|
+
export type Learned = {
|
|
72
|
+
/** When the medians were last computed; 0 before the first pass. */
|
|
73
|
+
at: number;
|
|
74
|
+
phases: Record<string, { medianSeconds: number; samples: number }>;
|
|
22
75
|
};
|
|
23
76
|
|
|
24
77
|
declare module 'claude-code' {
|
|
@@ -29,6 +82,9 @@ declare module 'claude-code' {
|
|
|
29
82
|
seen: string[];
|
|
30
83
|
/** False until the first scan, which records envelopes without a toast. */
|
|
31
84
|
isSeeded: boolean;
|
|
85
|
+
learned: Learned;
|
|
86
|
+
/** The focus Story the person hid the band for; it shows again on a new one. */
|
|
87
|
+
hiddenFor: number | null;
|
|
32
88
|
};
|
|
33
89
|
}
|
|
34
90
|
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-progress.schema.json",
|
|
4
|
+
"title": "story-progress",
|
|
5
|
+
"description": "The live progress record a Story's handoff and close rewrite at every step or phase change (Story #5553), at <tempRoot>/orchestration/story-progress-<id>.json. It exists because push, PR, review, auto-merge and the merge wait leave nothing on disk until the terminal envelope. Advisory only: nothing in Mandrel reads it to decide anything, every write is best effort, and each write is atomic (a <file>.tmp sibling renamed over the target).",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"additionalProperties": false,
|
|
8
|
+
"required": [
|
|
9
|
+
"kind",
|
|
10
|
+
"storyId",
|
|
11
|
+
"stage",
|
|
12
|
+
"phase",
|
|
13
|
+
"stageStartedAt",
|
|
14
|
+
"phaseStartedAt",
|
|
15
|
+
"prNumber",
|
|
16
|
+
"updatedAt"
|
|
17
|
+
],
|
|
18
|
+
"properties": {
|
|
19
|
+
"kind": { "type": "string", "const": "story-progress" },
|
|
20
|
+
"storyId": { "type": "integer", "minimum": 1 },
|
|
21
|
+
"stage": {
|
|
22
|
+
"type": "string",
|
|
23
|
+
"enum": ["handoff", "close"],
|
|
24
|
+
"description": "handoff — the worker's story-handoff.js run; close — single-story-close.js."
|
|
25
|
+
},
|
|
26
|
+
"phase": {
|
|
27
|
+
"type": "string",
|
|
28
|
+
"minLength": 1,
|
|
29
|
+
"description": "For close, the phase name close passes to setPhase (the phaseDurations keys). For handoff, the step name: preflight, base-merge, credited-run, seat, push, review."
|
|
30
|
+
},
|
|
31
|
+
"stageStartedAt": {
|
|
32
|
+
"type": "string",
|
|
33
|
+
"format": "date-time",
|
|
34
|
+
"description": "When this handoff or close run started; fixed for the run."
|
|
35
|
+
},
|
|
36
|
+
"phaseStartedAt": {
|
|
37
|
+
"type": "string",
|
|
38
|
+
"format": "date-time",
|
|
39
|
+
"description": "When the current phase started; resets on each phase change."
|
|
40
|
+
},
|
|
41
|
+
"prNumber": {
|
|
42
|
+
"type": ["integer", "null"],
|
|
43
|
+
"minimum": 1,
|
|
44
|
+
"description": "The Story PR's number from the moment close parses it; null before then and throughout handoff."
|
|
45
|
+
},
|
|
46
|
+
"updatedAt": { "type": "string", "format": "date-time" }
|
|
47
|
+
}
|
|
48
|
+
}
|
|
@@ -229,6 +229,21 @@ export function storyReviewDepositPath(sid, config) {
|
|
|
229
229
|
);
|
|
230
230
|
}
|
|
231
231
|
|
|
232
|
+
/**
|
|
233
|
+
* Live phase record for a Story's handoff or close. The trailing
|
|
234
|
+
* `-<id>` keys it to the Story for the retention purge.
|
|
235
|
+
*
|
|
236
|
+
* @param {number} sid
|
|
237
|
+
* @param {object} [config]
|
|
238
|
+
* @returns {string}
|
|
239
|
+
*/
|
|
240
|
+
export function storyProgressPath(sid, config) {
|
|
241
|
+
return path.join(
|
|
242
|
+
orchestrationLogDir(config),
|
|
243
|
+
`story-progress-${storyId(sid)}.json`,
|
|
244
|
+
);
|
|
245
|
+
}
|
|
246
|
+
|
|
232
247
|
const runId = (id) => {
|
|
233
248
|
if (!Number.isInteger(id) || id <= 0) {
|
|
234
249
|
throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);
|
|
@@ -30,6 +30,7 @@ import {
|
|
|
30
30
|
NEXT_COMMANDS,
|
|
31
31
|
terminalFromWaitOutcome,
|
|
32
32
|
} from '../story-deliver-terminal.js';
|
|
33
|
+
import { createStoryProgress } from '../story-progress.js';
|
|
33
34
|
import { deriveCloseNote } from './close-note.js';
|
|
34
35
|
import { closeArmedPr, runAutoMergePhase } from './phases/auto-merge.js';
|
|
35
36
|
import { runBaseSyncPhase } from './phases/base-sync.js';
|
|
@@ -430,6 +431,7 @@ async function openAndReviewPr(ctx, deps) {
|
|
|
430
431
|
progress,
|
|
431
432
|
});
|
|
432
433
|
const prNumber = parsePrNumber(prUrl);
|
|
434
|
+
ctx.recordPrNumber(prNumber);
|
|
433
435
|
// Already merged (landed between invocations): skip review and arm; confirm observes it.
|
|
434
436
|
if (alreadyMerged) {
|
|
435
437
|
discardHeldReview(ctx.heldReview, 'PR already merged', progress);
|
|
@@ -623,18 +625,34 @@ export async function runSingleStoryClose({
|
|
|
623
625
|
let phase = 'init';
|
|
624
626
|
let observedGates = null;
|
|
625
627
|
const phaseTimer = createPhaseTimer();
|
|
628
|
+
// Inert until the config resolves; no phase is entered before then.
|
|
629
|
+
let storyProgress = { phase() {}, prNumber() {} };
|
|
626
630
|
const setPhase = (next) => {
|
|
627
631
|
phase = next;
|
|
628
632
|
phaseTimer.enter(next);
|
|
633
|
+
storyProgress.phase(next);
|
|
629
634
|
};
|
|
630
635
|
const setObservedGates = (gates) => {
|
|
631
636
|
observedGates = gates;
|
|
632
637
|
};
|
|
633
638
|
try {
|
|
634
639
|
const startedAtMs = Date.now();
|
|
640
|
+
const deps = resolveCloseDeps(options, injected);
|
|
641
|
+
storyProgress = createStoryProgress({
|
|
642
|
+
storyId: options.storyId,
|
|
643
|
+
stage: 'close',
|
|
644
|
+
config: deps.config,
|
|
645
|
+
});
|
|
635
646
|
return await runClosePipeline(
|
|
636
|
-
{
|
|
637
|
-
|
|
647
|
+
{
|
|
648
|
+
options,
|
|
649
|
+
setPhase,
|
|
650
|
+
setObservedGates,
|
|
651
|
+
phaseTimer,
|
|
652
|
+
startedAtMs,
|
|
653
|
+
recordPrNumber: storyProgress.prNumber,
|
|
654
|
+
},
|
|
655
|
+
deps,
|
|
638
656
|
);
|
|
639
657
|
} catch (err) {
|
|
640
658
|
if (err && typeof err === 'object') {
|
|
@@ -1007,7 +1025,10 @@ async function resolveCloseWorktree(ctx, deps) {
|
|
|
1007
1025
|
!existingWorktreePath({ cwd, wtIsolation, storyId: ctx.storyId }) &&
|
|
1008
1026
|
resolveWorktreeEnabled({ config: deps.config });
|
|
1009
1027
|
ctx.landedPr = missing ? await findLandedPr(ctx, deps) : null;
|
|
1010
|
-
if (ctx.landedPr)
|
|
1028
|
+
if (ctx.landedPr) {
|
|
1029
|
+
ctx.recordPrNumber(ctx.landedPr.prNumber);
|
|
1030
|
+
return null;
|
|
1031
|
+
}
|
|
1011
1032
|
return await resolveStoryWorktree({
|
|
1012
1033
|
cwd,
|
|
1013
1034
|
config: deps.config,
|
|
@@ -38,6 +38,7 @@ import { getStoryBranch, gitSpawn } from '../git-utils.js';
|
|
|
38
38
|
import { readPackageScripts } from '../npm-scripts.js';
|
|
39
39
|
import { TIMEOUT_EXIT_CODE } from '../process-group.js';
|
|
40
40
|
import { probeHeldReviewDiff } from './review-deposit.js';
|
|
41
|
+
import { createStoryProgress, handoffStepName } from './story-progress.js';
|
|
41
42
|
import {
|
|
42
43
|
STATE_LABELS,
|
|
43
44
|
transitionTicketState,
|
|
@@ -815,7 +816,13 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
|
|
|
815
816
|
const steps = [];
|
|
816
817
|
let stop = precheck(ctx);
|
|
817
818
|
if (stop) steps.push(stop);
|
|
819
|
+
const storyProgress = createStoryProgress({
|
|
820
|
+
storyId,
|
|
821
|
+
stage: 'handoff',
|
|
822
|
+
config,
|
|
823
|
+
});
|
|
818
824
|
for (const step of stop ? [] : stepOrder(ctx.depositor)) {
|
|
825
|
+
storyProgress.phase(handoffStepName(step));
|
|
819
826
|
const result = await step(ctx);
|
|
820
827
|
steps.push(result);
|
|
821
828
|
progress(result.name, `${result.outcome} — ${result.detail}`);
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The live story-progress record: which handoff step or close
|
|
3
|
+
* phase a Story is in right now, so live tooling can see the post-validation
|
|
4
|
+
* close phases that otherwise leave nothing on disk until the terminal
|
|
5
|
+
* envelope. Shape: `.agents/schemas/story-progress.schema.json`.
|
|
6
|
+
*
|
|
7
|
+
* Advisory only — nothing in Mandrel decides on it. Every write is best
|
|
8
|
+
* effort (an fs error is swallowed and logged at debug) and atomic (a
|
|
9
|
+
* `<file>.tmp` sibling renamed over the target), so a poller never parses
|
|
10
|
+
* half a file and an unwritable temp folder changes no delivery outcome.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import fs from 'node:fs';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
|
|
16
|
+
import { storyProgressPath } from '../config/temp-paths.js';
|
|
17
|
+
import { Logger } from '../Logger.js';
|
|
18
|
+
|
|
19
|
+
const STORY_PROGRESS_KIND = 'story-progress';
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* A handoff step's reported name from its function name: `stepBaseMerge` →
|
|
23
|
+
* `base-merge`. The handoff suite pins that these equal the names each step
|
|
24
|
+
* reports in its envelope.
|
|
25
|
+
*
|
|
26
|
+
* @param {Function} step
|
|
27
|
+
* @returns {string}
|
|
28
|
+
*/
|
|
29
|
+
export function handoffStepName(step) {
|
|
30
|
+
return step.name
|
|
31
|
+
.replace(/^step/, '')
|
|
32
|
+
.replace(/[A-Z]/g, (c, i) => `${i > 0 ? '-' : ''}${c.toLowerCase()}`);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Write `record` to `file` atomically. Never throws.
|
|
37
|
+
*
|
|
38
|
+
* @param {string} file
|
|
39
|
+
* @param {object} record
|
|
40
|
+
* @param {{ fsImpl?: typeof fs, debug?: (msg: string) => void }} [deps]
|
|
41
|
+
* @returns {boolean} whether the record landed
|
|
42
|
+
*/
|
|
43
|
+
function writeStoryProgress(file, record, deps = {}) {
|
|
44
|
+
const fsImpl = deps.fsImpl ?? fs;
|
|
45
|
+
const debug = deps.debug ?? ((msg) => Logger.debug(msg));
|
|
46
|
+
const tmp = `${file}.tmp`;
|
|
47
|
+
try {
|
|
48
|
+
fsImpl.mkdirSync(path.dirname(file), { recursive: true });
|
|
49
|
+
fsImpl.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
|
|
50
|
+
fsImpl.renameSync(tmp, file);
|
|
51
|
+
return true;
|
|
52
|
+
} catch (err) {
|
|
53
|
+
try {
|
|
54
|
+
fsImpl.rmSync(tmp, { force: true });
|
|
55
|
+
} catch {
|
|
56
|
+
// The stray tmp is harmless; the next write overwrites it.
|
|
57
|
+
}
|
|
58
|
+
debug(`[story-progress] write skipped for ${file}: ${err?.message ?? err}`);
|
|
59
|
+
return false;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* A per-run recorder: `stageStartedAt` is fixed at creation, `phaseStartedAt`
|
|
65
|
+
* resets on each `phase()`, and `prNumber()` re-writes the current phase with
|
|
66
|
+
* the PR number once known. Nothing is written until the first `phase()`.
|
|
67
|
+
* Construction never throws either: a bad Story id or config degrades to a
|
|
68
|
+
* recorder that writes nothing.
|
|
69
|
+
*
|
|
70
|
+
* @param {{ storyId: number, stage: 'handoff'|'close', config?: object,
|
|
71
|
+
* file?: string, now?: () => Date, fsImpl?: typeof fs,
|
|
72
|
+
* debug?: (msg: string) => void }} args
|
|
73
|
+
* @returns {{ phase: (name: string) => boolean, prNumber: (n: number|null) => boolean, file: string|null }}
|
|
74
|
+
*/
|
|
75
|
+
export function createStoryProgress({
|
|
76
|
+
storyId,
|
|
77
|
+
stage,
|
|
78
|
+
config,
|
|
79
|
+
file,
|
|
80
|
+
now = () => new Date(),
|
|
81
|
+
fsImpl,
|
|
82
|
+
debug,
|
|
83
|
+
}) {
|
|
84
|
+
let target = file ?? null;
|
|
85
|
+
if (!target) {
|
|
86
|
+
try {
|
|
87
|
+
target = storyProgressPath(storyId, config);
|
|
88
|
+
} catch (err) {
|
|
89
|
+
(debug ?? ((msg) => Logger.debug(msg)))(
|
|
90
|
+
`[story-progress] no progress path: ${err?.message ?? err}`,
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
const stageStartedAt = now().toISOString();
|
|
95
|
+
let current = null;
|
|
96
|
+
let phaseStartedAt = stageStartedAt;
|
|
97
|
+
let pr = null;
|
|
98
|
+
const write = () => {
|
|
99
|
+
if (!target || current === null) return false;
|
|
100
|
+
return writeStoryProgress(
|
|
101
|
+
target,
|
|
102
|
+
{
|
|
103
|
+
kind: STORY_PROGRESS_KIND,
|
|
104
|
+
storyId,
|
|
105
|
+
stage,
|
|
106
|
+
phase: current,
|
|
107
|
+
stageStartedAt,
|
|
108
|
+
phaseStartedAt,
|
|
109
|
+
prNumber: pr,
|
|
110
|
+
updatedAt: now().toISOString(),
|
|
111
|
+
},
|
|
112
|
+
{ fsImpl, debug },
|
|
113
|
+
);
|
|
114
|
+
};
|
|
115
|
+
return {
|
|
116
|
+
file: target,
|
|
117
|
+
phase(name) {
|
|
118
|
+
current = name;
|
|
119
|
+
phaseStartedAt = now().toISOString();
|
|
120
|
+
return write();
|
|
121
|
+
},
|
|
122
|
+
prNumber(n) {
|
|
123
|
+
pr = Number.isInteger(n) && n > 0 ? n : null;
|
|
124
|
+
return write();
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
}
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,14 @@ 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.75.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.74.0...mandrel-v2.75.0) (2026-10-02)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* close and handoff write a story-progress file at every phase change, so live tooling can see post-validation close phases ([#5553](https://github.com/dsj1984/mandrel/issues/5553)) ([#5554](https://github.com/dsj1984/mandrel/issues/5554)) ([84c9a87](https://github.com/dsj1984/mandrel/commit/84c9a87c46253601e0ccbe681d0b9bd41eb20a4a))
|
|
24
|
+
* **mods:** mandrel-status band v2 with stage strip, learned ETAs and run line (refs [#5552](https://github.com/dsj1984/mandrel/issues/5552)) ([#5555](https://github.com/dsj1984/mandrel/issues/5555)) ([d194043](https://github.com/dsj1984/mandrel/commit/d194043b554bfb96371bfbc4ab0029b0c445bc9e))
|
|
25
|
+
|
|
18
26
|
## [2.74.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.73.0...mandrel-v2.74.0) (2026-10-02)
|
|
19
27
|
|
|
20
28
|
|
package/package.json
CHANGED