mandrel 2.84.0 → 2.86.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/agentrc-reference.json +2 -1
- package/.agents/docs/configuration.md +4 -2
- package/.agents/schemas/agentrc.schema.json +41 -2
- package/.agents/schemas/story-deliver-terminal.schema.json +2 -2
- package/.agents/scripts/coverage-capture.js +1 -0
- package/.agents/scripts/evidence-gate.js +3 -2
- package/.agents/scripts/lib/close-lock-events.js +29 -9
- package/.agents/scripts/lib/close-validation/process.js +6 -0
- package/.agents/scripts/lib/close-validation/runner.js +22 -6
- package/.agents/scripts/lib/config-settings-schema-delivery.js +41 -2
- package/.agents/scripts/lib/full-suite-lock.js +100 -38
- package/.agents/scripts/lib/full-suite-queue.js +104 -37
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +242 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +151 -111
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +30 -4
- package/.agents/scripts/lib/orchestration/story-handoff.js +103 -11
- package/.agents/scripts/lib/suite-admission.js +410 -0
- package/.agents/workflows/helpers/deliver-story-reference.md +6 -0
- package/docs/CHANGELOG.md +15 -0
- package/package.json +1 -1
|
@@ -23,6 +23,7 @@ import path from 'node:path';
|
|
|
23
23
|
import { fileURLToPath } from 'node:url';
|
|
24
24
|
|
|
25
25
|
import { spawnCaptureAsync } from '../child-exec.js';
|
|
26
|
+
import { createLockEventChannel } from '../close-lock-events.js';
|
|
26
27
|
import {
|
|
27
28
|
resolveLintCommand,
|
|
28
29
|
resolveTestGateArgv,
|
|
@@ -35,11 +36,15 @@ import {
|
|
|
35
36
|
orchestrationLogDir,
|
|
36
37
|
storyReviewDepositPath,
|
|
37
38
|
} from '../config/temp-paths.js';
|
|
38
|
-
import {
|
|
39
|
+
import {
|
|
40
|
+
ADMISSION_REFUSED_EXIT_CODE,
|
|
41
|
+
LOCK_WAIT_EXPIRED_EXIT_CODE,
|
|
42
|
+
} from '../full-suite-lock.js';
|
|
39
43
|
import { syncBranchFromBase } from '../git/sync-from-base.js';
|
|
40
44
|
import { getStoryBranch, gitSpawn } from '../git-utils.js';
|
|
41
45
|
import { readPackageScripts } from '../npm-scripts.js';
|
|
42
46
|
import { TIMEOUT_EXIT_CODE } from '../process-group.js';
|
|
47
|
+
import { describeBlocking } from '../suite-admission.js';
|
|
43
48
|
import { probeHeldReviewDiff } from './review-deposit.js';
|
|
44
49
|
import { createStoryProgress, handoffStepName } from './story-progress.js';
|
|
45
50
|
import {
|
|
@@ -109,6 +114,14 @@ const RATCHETS = Object.freeze([
|
|
|
109
114
|
|
|
110
115
|
const MAX_OFFENDING_LINES = 10;
|
|
111
116
|
|
|
117
|
+
const LOCK_POLL_MS = 1_000;
|
|
118
|
+
|
|
119
|
+
function defaultSleep(ms) {
|
|
120
|
+
return new Promise((resolve) => {
|
|
121
|
+
setTimeout(resolve, ms).unref?.();
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
|
|
112
125
|
const SEAT_SCRIPTS = Object.freeze({
|
|
113
126
|
crap: 'update-crap-baseline.js',
|
|
114
127
|
maintainability: 'update-maintainability-baseline.js',
|
|
@@ -174,16 +187,81 @@ function headSha(ctx) {
|
|
|
174
187
|
* @param {string} logName
|
|
175
188
|
* @param {string} cmd
|
|
176
189
|
* @param {string[]} args
|
|
190
|
+
* @param {Record<string, string|undefined>} [env] the child's whole env.
|
|
177
191
|
* @returns {Promise<{ status: number, output: string, evidencePath: string }>}
|
|
178
192
|
*/
|
|
179
|
-
async function runLogged(ctx, logName, cmd, args) {
|
|
193
|
+
async function runLogged(ctx, logName, cmd, args, env) {
|
|
180
194
|
ctx.progress(logName, `${cmd} ${args.join(' ')}`);
|
|
181
|
-
const res = await ctx.runCommand(cmd, args, { cwd: ctx.cwd });
|
|
195
|
+
const res = await ctx.runCommand(cmd, args, { cwd: ctx.cwd, env });
|
|
182
196
|
const output = [res.stdout, res.stderr].filter(Boolean).join('\n');
|
|
183
197
|
const evidencePath = ctx.writeEvidence(logName, output);
|
|
184
198
|
return { status: res.status, output, evidencePath };
|
|
185
199
|
}
|
|
186
200
|
|
|
201
|
+
const LOCK_PHASE_TEXT = Object.freeze({
|
|
202
|
+
waiting: 'waiting for the full-suite lock',
|
|
203
|
+
'still-waiting': 'still waiting for the full-suite lock',
|
|
204
|
+
admitted: 'admitted — suite running',
|
|
205
|
+
// Older children report `acquired`, the same state as `admitted`.
|
|
206
|
+
acquired: 'acquired the full-suite lock',
|
|
207
|
+
completed: 'suite completed',
|
|
208
|
+
expired: 'gave up waiting for the full-suite lock',
|
|
209
|
+
});
|
|
210
|
+
|
|
211
|
+
/** @param {import('../full-suite-queue.js').LockProgress} event */
|
|
212
|
+
function describeLockProgress(event) {
|
|
213
|
+
const head = LOCK_PHASE_TEXT[event.phase] ?? `lock ${event.phase}`;
|
|
214
|
+
if (event.phase === 'completed') return `${head} (${durations(event)})`;
|
|
215
|
+
const parts = [
|
|
216
|
+
`waited ${event.waitedSeconds}s of a ${event.waitBudgetSeconds}s budget`,
|
|
217
|
+
];
|
|
218
|
+
if (event.blocking)
|
|
219
|
+
parts.push(`blocked: ${describeBlocking(event.blocking)}`);
|
|
220
|
+
const { holder, queueAhead } = event;
|
|
221
|
+
if (holder) {
|
|
222
|
+
parts.push(
|
|
223
|
+
`holder ${holder.ownerId ?? 'unknown'}, pid ${holder.pid ?? 'unknown'}, lock age ${holder.ageSeconds ?? 'unknown'}s`,
|
|
224
|
+
);
|
|
225
|
+
}
|
|
226
|
+
if (Number.isInteger(queueAhead)) parts.push(`${queueAhead} ahead in queue`);
|
|
227
|
+
return `${head} (${parts.join('; ')})`;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
function durations({ waitMs, executionMs }) {
|
|
231
|
+
const seconds = (ms) => `${Math.round((ms ?? 0) / 1000)}s`;
|
|
232
|
+
return `waited ${seconds(waitMs)}, ran ${seconds(executionMs)}`;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Tail a fresh lock-event channel while `run(env)` runs, forwarding each
|
|
237
|
+
* `lock-progress` event once; never the child's output, which can be forged.
|
|
238
|
+
*/
|
|
239
|
+
async function withLockProgress(ctx, run) {
|
|
240
|
+
const channel = ctx.createLockChannel();
|
|
241
|
+
const forward = () => {
|
|
242
|
+
for (const event of channel.drain()) {
|
|
243
|
+
if (event.kind === 'lock-progress') {
|
|
244
|
+
ctx.progress('LOCK', describeLockProgress(event));
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
};
|
|
248
|
+
let running = true;
|
|
249
|
+
// Not awaited: the final drain below forwards anything it would have.
|
|
250
|
+
(async () => {
|
|
251
|
+
while (running) {
|
|
252
|
+
await ctx.sleep(ctx.lockPollMs);
|
|
253
|
+
if (running) forward();
|
|
254
|
+
}
|
|
255
|
+
})().catch(() => {});
|
|
256
|
+
try {
|
|
257
|
+
return await run({ ...ctx.env, ...channel.env });
|
|
258
|
+
} finally {
|
|
259
|
+
running = false;
|
|
260
|
+
forward();
|
|
261
|
+
channel.dispose();
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
|
|
187
265
|
/**
|
|
188
266
|
* The suite exit codes § 5 distinguishes from a red run.
|
|
189
267
|
*
|
|
@@ -194,6 +272,9 @@ function describeSuiteFailure(status) {
|
|
|
194
272
|
if (status === LOCK_WAIT_EXPIRED_EXIT_CODE) {
|
|
195
273
|
return `suite deferred (exit ${status}): another full suite holds the host lock — re-run the handoff once it frees`;
|
|
196
274
|
}
|
|
275
|
+
if (status === ADMISSION_REFUSED_EXIT_CODE) {
|
|
276
|
+
return `suite refused (exit ${status}): its declared delivery.execution.workloads weight exceeds capacity — fix the declaration, then re-run`;
|
|
277
|
+
}
|
|
197
278
|
if (status === TIMEOUT_EXIT_CODE) {
|
|
198
279
|
return `suite timed out (exit ${status}) — usually host contention; re-run the handoff`;
|
|
199
280
|
}
|
|
@@ -354,13 +435,9 @@ async function stepCreditedRun(ctx) {
|
|
|
354
435
|
);
|
|
355
436
|
}
|
|
356
437
|
const capture = ctx.depositor === 'coverage-capture';
|
|
357
|
-
const
|
|
358
|
-
?
|
|
359
|
-
|
|
360
|
-
'--cwd',
|
|
361
|
-
ctx.cwd,
|
|
362
|
-
])
|
|
363
|
-
: await runLogged(ctx, 'credited-run', 'node', [
|
|
438
|
+
const args = capture
|
|
439
|
+
? [path.join(SCRIPTS_DIR, 'coverage-capture.js'), '--cwd', ctx.cwd]
|
|
440
|
+
: [
|
|
364
441
|
path.join(SCRIPTS_DIR, 'evidence-gate.js'),
|
|
365
442
|
'--standalone',
|
|
366
443
|
'--scope-id',
|
|
@@ -372,7 +449,10 @@ async function stepCreditedRun(ctx) {
|
|
|
372
449
|
'--',
|
|
373
450
|
// Close's `test` gate argv, so the deposit keys on its credit identity.
|
|
374
451
|
...testGateArgv(ctx.config),
|
|
375
|
-
]
|
|
452
|
+
];
|
|
453
|
+
const run = await withLockProgress(ctx, (env) =>
|
|
454
|
+
runLogged(ctx, 'credited-run', 'node', args, env),
|
|
455
|
+
);
|
|
376
456
|
const extra = { evidencePath: run.evidencePath, depositor: ctx.depositor };
|
|
377
457
|
if (run.status !== 0) {
|
|
378
458
|
return fixRequired(name, describeSuiteFailure(run.status), extra);
|
|
@@ -769,6 +849,10 @@ async function defaultBlock({
|
|
|
769
849
|
* createProviderFn?: Function,
|
|
770
850
|
* progress?: (tag: string, msg: string) => void,
|
|
771
851
|
* logDir?: string,
|
|
852
|
+
* createLockChannel?: typeof createLockEventChannel,
|
|
853
|
+
* sleep?: (ms: number) => Promise<void>,
|
|
854
|
+
* lockPollMs?: number,
|
|
855
|
+
* env?: Record<string, string|undefined>,
|
|
772
856
|
* }} deps
|
|
773
857
|
* @returns {Promise<{ envelope: object, exitCode: number }>}
|
|
774
858
|
*/
|
|
@@ -784,6 +868,10 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
|
|
|
784
868
|
createProviderFn,
|
|
785
869
|
progress = () => {},
|
|
786
870
|
logDir = orchestrationLogDir(config),
|
|
871
|
+
createLockChannel = createLockEventChannel,
|
|
872
|
+
sleep = defaultSleep,
|
|
873
|
+
lockPollMs = LOCK_POLL_MS,
|
|
874
|
+
env = process.env,
|
|
787
875
|
} = deps;
|
|
788
876
|
const block =
|
|
789
877
|
deps.block ??
|
|
@@ -808,6 +896,10 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
|
|
|
808
896
|
probeReview,
|
|
809
897
|
computeReview,
|
|
810
898
|
progress,
|
|
899
|
+
createLockChannel,
|
|
900
|
+
sleep,
|
|
901
|
+
lockPollMs,
|
|
902
|
+
env,
|
|
811
903
|
state: readState(statePath),
|
|
812
904
|
review: null,
|
|
813
905
|
reviewPath: storyReviewDepositPath(storyId, config),
|
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* suite-admission.js — capacity admission for the suite spawns the
|
|
3
|
+
* full-suite lock guards.
|
|
4
|
+
*
|
|
5
|
+
* A spawn is classified by its exact argv against
|
|
6
|
+
* `delivery.execution.workloads[]`. A declared workload holds a
|
|
7
|
+
* weight-carrying reservation under the main checkout's `.git`, admitted while
|
|
8
|
+
* live weights fit `capacity` and no live reservation shares a resource. An
|
|
9
|
+
* undeclared spawn is exclusive: it takes the legacy lockfile (so older
|
|
10
|
+
* Mandrel versions still queue behind it) and drains every reservation first.
|
|
11
|
+
* Check-then-reserve runs under a short admission mutex, so two processes can
|
|
12
|
+
* never both take the last slot.
|
|
13
|
+
*/
|
|
14
|
+
import crypto from 'node:crypto';
|
|
15
|
+
import os from 'node:os';
|
|
16
|
+
import path from 'node:path';
|
|
17
|
+
|
|
18
|
+
import {
|
|
19
|
+
acquireSweepLock,
|
|
20
|
+
isHolderAlive,
|
|
21
|
+
readLockHolderPid,
|
|
22
|
+
} from './single-story-sweep/sweep-lock.js';
|
|
23
|
+
|
|
24
|
+
/** `EX_CONFIG`: a declared weight the capacity can never admit. */
|
|
25
|
+
export const ADMISSION_REFUSED_EXIT_CODE = 78;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Staleness for every holder, reservation and ticket — fixed, so no waiter's
|
|
29
|
+
* own wait budget can read a live holder stale. A dead pid is stale at once.
|
|
30
|
+
*/
|
|
31
|
+
export const FULL_SUITE_STALE_MS = 1_800_000;
|
|
32
|
+
|
|
33
|
+
/** Holders refresh well inside every stale threshold, old or new. */
|
|
34
|
+
const HOLDER_HEARTBEAT_MS = 20_000;
|
|
35
|
+
|
|
36
|
+
const MUTEX_STALE_MS = 30_000;
|
|
37
|
+
|
|
38
|
+
const RESERVATION_RE = /^w(\d+)~([a-z0-9+-]*)~[^~]+\.lock$/;
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* @typedef {{ kind: 'exclusive' }
|
|
42
|
+
* | { kind: 'declared', command: string, weight: number, resources: string[] }
|
|
43
|
+
* | { kind: 'refused', command: string, weight: number, capacity: number }} SuiteWorkload
|
|
44
|
+
*/
|
|
45
|
+
|
|
46
|
+
/** @param {string|string[]} argv */
|
|
47
|
+
function normalizeCommand(argv) {
|
|
48
|
+
const text = Array.isArray(argv) ? argv.join(' ') : String(argv ?? '');
|
|
49
|
+
return text.split(/\s+/).filter(Boolean).join(' ');
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* @param {object} [config]
|
|
54
|
+
* @param {{ availableParallelism?: () => number }} [osImpl]
|
|
55
|
+
* @returns {number}
|
|
56
|
+
*/
|
|
57
|
+
export function resolveSuiteCapacity(config, osImpl = os) {
|
|
58
|
+
const configured = config?.delivery?.execution?.capacity;
|
|
59
|
+
if (Number.isInteger(configured) && configured >= 1) return configured;
|
|
60
|
+
return Math.max(1, Number(osImpl.availableParallelism?.()) || 1);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Exact argv equality only — never a prefix, flag or diff-size inference.
|
|
65
|
+
*
|
|
66
|
+
* @param {{ config?: object, argv?: string|string[], capacity?: number }} opts
|
|
67
|
+
* @returns {SuiteWorkload}
|
|
68
|
+
*/
|
|
69
|
+
function classifySuiteWorkload({ config, argv, capacity }) {
|
|
70
|
+
const workloads = config?.delivery?.execution?.workloads;
|
|
71
|
+
if (!Array.isArray(workloads) || argv === undefined) {
|
|
72
|
+
return { kind: 'exclusive' };
|
|
73
|
+
}
|
|
74
|
+
const command = normalizeCommand(argv);
|
|
75
|
+
const entry = workloads.find(
|
|
76
|
+
(w) => normalizeCommand(w?.command) === command && command !== '',
|
|
77
|
+
);
|
|
78
|
+
if (!entry) return { kind: 'exclusive' };
|
|
79
|
+
const limit = capacity ?? resolveSuiteCapacity(config);
|
|
80
|
+
if (entry.weight > limit) {
|
|
81
|
+
return { kind: 'refused', command, weight: entry.weight, capacity: limit };
|
|
82
|
+
}
|
|
83
|
+
return {
|
|
84
|
+
kind: 'declared',
|
|
85
|
+
command,
|
|
86
|
+
weight: entry.weight,
|
|
87
|
+
resources: [...(entry.resources ?? [])],
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* @param {object} [config]
|
|
93
|
+
* @param {string[]} [argv]
|
|
94
|
+
* @returns {{ capacity: number, workload: SuiteWorkload }}
|
|
95
|
+
*/
|
|
96
|
+
export function resolveAdmission(config, argv) {
|
|
97
|
+
const capacity = resolveSuiteCapacity(config);
|
|
98
|
+
return {
|
|
99
|
+
capacity,
|
|
100
|
+
workload: classifySuiteWorkload({ config, argv, capacity }),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** @param {{ workload?: SuiteWorkload }} opts */
|
|
105
|
+
export function createAttempt(opts) {
|
|
106
|
+
return opts.workload?.kind === 'declared'
|
|
107
|
+
? createDeclaredAttempt(opts)
|
|
108
|
+
: createExclusiveAttempt(opts);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** The `completed` progress event: wait and execution kept apart. */
|
|
112
|
+
export function completedProgress(waitMs, budgetMs, executionMs) {
|
|
113
|
+
return {
|
|
114
|
+
phase: 'completed',
|
|
115
|
+
waitedSeconds: Math.round(waitMs / 1000),
|
|
116
|
+
waitBudgetSeconds: Math.round(Math.max(0, budgetMs) / 1000),
|
|
117
|
+
waitMs,
|
|
118
|
+
executionMs: Math.max(0, executionMs),
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** @param {SuiteWorkload} workload */
|
|
123
|
+
export function describeRefusal({ command, weight, capacity }) {
|
|
124
|
+
return `[full-suite-lock] ✖ \`${command}\` declares weight ${weight}, above delivery.execution.capacity ${capacity} — it can never be admitted, so nothing ran and no credit was recorded. Lower its weight or raise capacity. Exiting ${ADMISSION_REFUSED_EXIT_CODE}.`;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function reservationsDir(lockPath) {
|
|
128
|
+
return `${lockPath}.reservations`;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
function ageOf(file, fsImpl, nowFn) {
|
|
132
|
+
try {
|
|
133
|
+
return nowFn() - fsImpl.statSync(file).mtimeMs;
|
|
134
|
+
} catch {
|
|
135
|
+
return null;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Dead pid → stale now; otherwise a heartbeat older than `staleMs`.
|
|
141
|
+
*
|
|
142
|
+
* @returns {{ live: boolean, exists: boolean, pid: number|null, ageMs: number|null }}
|
|
143
|
+
*/
|
|
144
|
+
function holderState(file, { fsImpl, nowFn, staleMs, killFn }) {
|
|
145
|
+
const ageMs = ageOf(file, fsImpl, nowFn);
|
|
146
|
+
if (ageMs === null) return { live: false, exists: false, pid: null, ageMs };
|
|
147
|
+
const pid = readLockHolderPid(file, fsImpl);
|
|
148
|
+
const dead = isHolderAlive(pid, killFn) === false;
|
|
149
|
+
return { live: !dead && ageMs <= staleMs, exists: true, pid, ageMs };
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function holderOf(file, state) {
|
|
153
|
+
return {
|
|
154
|
+
ownerId: path.basename(file),
|
|
155
|
+
pid: state.pid,
|
|
156
|
+
ageSeconds: Math.max(0, Math.round(state.ageMs / 1000)),
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Live reservations; a dead-pid entry is unlinked (callers hold the mutex).
|
|
162
|
+
*
|
|
163
|
+
* @returns {Array<{ weight: number, resources: string[], holder: object }>|null}
|
|
164
|
+
* `null` when the directory is absent.
|
|
165
|
+
*/
|
|
166
|
+
function readLiveReservations({ lockPath, ...probe }) {
|
|
167
|
+
const dir = reservationsDir(lockPath);
|
|
168
|
+
let names;
|
|
169
|
+
try {
|
|
170
|
+
names = probe.fsImpl.readdirSync(dir).map(String).sort();
|
|
171
|
+
} catch {
|
|
172
|
+
return null;
|
|
173
|
+
}
|
|
174
|
+
return names.flatMap((name) => liveReservation(dir, name, probe));
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function liveReservation(dir, name, probe) {
|
|
178
|
+
const match = RESERVATION_RE.exec(name);
|
|
179
|
+
if (!match) return [];
|
|
180
|
+
const file = path.join(dir, name);
|
|
181
|
+
const state = holderState(file, probe);
|
|
182
|
+
if (!state.live) {
|
|
183
|
+
if (state.exists && isHolderAlive(state.pid, probe.killFn) === false) {
|
|
184
|
+
unlinkQuietly(file, probe.fsImpl);
|
|
185
|
+
}
|
|
186
|
+
return [];
|
|
187
|
+
}
|
|
188
|
+
return [
|
|
189
|
+
{
|
|
190
|
+
weight: Number(match[1]),
|
|
191
|
+
resources: match[2] ? match[2].split('+') : [],
|
|
192
|
+
holder: holderOf(file, state),
|
|
193
|
+
},
|
|
194
|
+
];
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function unlinkQuietly(file, fsImpl) {
|
|
198
|
+
try {
|
|
199
|
+
fsImpl.unlinkSync(file);
|
|
200
|
+
} catch {}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** @returns {object|null} the live legacy holder, if any. */
|
|
204
|
+
function liveLegacyHolder({ lockPath, ...probe }) {
|
|
205
|
+
const state = holderState(lockPath, probe);
|
|
206
|
+
return state.live ? holderOf(lockPath, state) : null;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* Runs `fn` under the admission mutex. `busy` retries next poll; `error`
|
|
211
|
+
* fails open, as every lockfile I/O error does.
|
|
212
|
+
*/
|
|
213
|
+
function underAdmissionMutex({ lockPath, fsImpl }, fn) {
|
|
214
|
+
const mutex = acquireSweepLock({
|
|
215
|
+
lockPath: `${lockPath}.admission`,
|
|
216
|
+
timeoutMs: MUTEX_STALE_MS,
|
|
217
|
+
heartbeatMs: 0,
|
|
218
|
+
fsImpl,
|
|
219
|
+
processImpl: null,
|
|
220
|
+
});
|
|
221
|
+
if (!mutex.acquired) {
|
|
222
|
+
return mutex.reason === 'error'
|
|
223
|
+
? { acquired: false, reason: 'error' }
|
|
224
|
+
: { acquired: false, blocking: { reason: 'admission' } };
|
|
225
|
+
}
|
|
226
|
+
try {
|
|
227
|
+
return fn();
|
|
228
|
+
} finally {
|
|
229
|
+
mutex.release();
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
function blocked(blocking) {
|
|
234
|
+
return { acquired: false, blocking };
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
function sharedResource(live, resources) {
|
|
238
|
+
for (const reservation of live) {
|
|
239
|
+
const shared = reservation.resources.find((r) => resources.includes(r));
|
|
240
|
+
if (shared) return { shared, holder: reservation.holder };
|
|
241
|
+
}
|
|
242
|
+
return null;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
function reservationName({ weight, resources }) {
|
|
246
|
+
const rand = crypto.randomBytes(4).toString('hex');
|
|
247
|
+
return `w${weight}~${resources.join('+')}~${process.pid}-${rand}.lock`;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* A declared run: admitted when no exclusive holder is live, no live
|
|
252
|
+
* reservation shares a resource, and the live weights plus its own fit.
|
|
253
|
+
*
|
|
254
|
+
* @param {{ lockPath: string, workload: SuiteWorkload, capacity: number,
|
|
255
|
+
* staleMs: number, fsImpl: object, nowFn: () => number, killFn?: Function,
|
|
256
|
+
* acquireReservationFn?: typeof acquireSweepLock }} opts
|
|
257
|
+
*/
|
|
258
|
+
function createDeclaredAttempt(opts) {
|
|
259
|
+
const { workload, capacity } = opts;
|
|
260
|
+
const acquire = opts.acquireReservationFn ?? acquireSweepLock;
|
|
261
|
+
let held = null;
|
|
262
|
+
const admit = () => {
|
|
263
|
+
const legacy = liveLegacyHolder(opts);
|
|
264
|
+
if (legacy) return blocked({ reason: 'exclusive', holder: legacy });
|
|
265
|
+
const live = readLiveReservations(opts) ?? [];
|
|
266
|
+
const clash = sharedResource(live, workload.resources);
|
|
267
|
+
if (clash) {
|
|
268
|
+
return blocked({
|
|
269
|
+
reason: 'resource',
|
|
270
|
+
resource: clash.shared,
|
|
271
|
+
holder: clash.holder,
|
|
272
|
+
});
|
|
273
|
+
}
|
|
274
|
+
const used = live.reduce((sum, r) => sum + r.weight, 0);
|
|
275
|
+
if (used + workload.weight > capacity) {
|
|
276
|
+
return blocked({
|
|
277
|
+
reason: 'capacity',
|
|
278
|
+
used,
|
|
279
|
+
requested: workload.weight,
|
|
280
|
+
capacity,
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
return reserve();
|
|
284
|
+
};
|
|
285
|
+
const reserve = () => {
|
|
286
|
+
const dir = reservationsDir(opts.lockPath);
|
|
287
|
+
try {
|
|
288
|
+
opts.fsImpl.mkdirSync(dir, { recursive: true });
|
|
289
|
+
} catch {
|
|
290
|
+
return { acquired: false, reason: 'error' };
|
|
291
|
+
}
|
|
292
|
+
const result = acquire({
|
|
293
|
+
lockPath: path.join(dir, reservationName(workload)),
|
|
294
|
+
timeoutMs: opts.staleMs,
|
|
295
|
+
heartbeatMs: HOLDER_HEARTBEAT_MS,
|
|
296
|
+
fsImpl: opts.fsImpl,
|
|
297
|
+
});
|
|
298
|
+
if (result.acquired) held = result;
|
|
299
|
+
return result.acquired ? result : { acquired: false, reason: 'error' };
|
|
300
|
+
};
|
|
301
|
+
return {
|
|
302
|
+
tryOnce: () => underAdmissionMutex(opts, admit),
|
|
303
|
+
release: () => held?.release(),
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* An undeclared run: take the legacy lockfile, then wait (still holding it,
|
|
309
|
+
* so nothing new is admitted) until every live reservation has drained.
|
|
310
|
+
*
|
|
311
|
+
* @param {{ lockPath: string, capacity: number, staleMs: number,
|
|
312
|
+
* fsImpl: object, nowFn: () => number, killFn?: Function,
|
|
313
|
+
* acquireOnceFn: typeof acquireSweepLock }} opts
|
|
314
|
+
*/
|
|
315
|
+
function createExclusiveAttempt(opts) {
|
|
316
|
+
let held = null;
|
|
317
|
+
const drained = () => {
|
|
318
|
+
const live = readLiveReservations(opts);
|
|
319
|
+
if (live === null || live.length === 0) return held;
|
|
320
|
+
return blocked({
|
|
321
|
+
reason: 'capacity',
|
|
322
|
+
used: live.reduce((sum, r) => sum + r.weight, 0),
|
|
323
|
+
requested: opts.capacity,
|
|
324
|
+
capacity: opts.capacity,
|
|
325
|
+
holder: live[0].holder,
|
|
326
|
+
});
|
|
327
|
+
};
|
|
328
|
+
const tryOnce = () => {
|
|
329
|
+
if (!held) {
|
|
330
|
+
const first = opts.acquireOnceFn({
|
|
331
|
+
lockPath: opts.lockPath,
|
|
332
|
+
timeoutMs: opts.staleMs,
|
|
333
|
+
heartbeatMs: HOLDER_HEARTBEAT_MS,
|
|
334
|
+
fsImpl: opts.fsImpl,
|
|
335
|
+
});
|
|
336
|
+
if (!first.acquired) return first;
|
|
337
|
+
held = first;
|
|
338
|
+
}
|
|
339
|
+
if (!hasReservations(opts)) return held;
|
|
340
|
+
const verdict = underAdmissionMutex(opts, drained);
|
|
341
|
+
return verdict.reason === 'error' ? held : verdict;
|
|
342
|
+
};
|
|
343
|
+
return {
|
|
344
|
+
tryOnce,
|
|
345
|
+
release: () => held?.release(),
|
|
346
|
+
};
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
function hasReservations({ lockPath, fsImpl }) {
|
|
350
|
+
try {
|
|
351
|
+
return fsImpl.readdirSync(reservationsDir(lockPath)).length > 0;
|
|
352
|
+
} catch {
|
|
353
|
+
return false;
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
const LOCK_TAG = '[full-suite-lock]';
|
|
358
|
+
|
|
359
|
+
/** The declared-run wait line; `null` leaves the exclusive wording. */
|
|
360
|
+
export function admissionWaitLine(workload, blocking, waitMs) {
|
|
361
|
+
if (workload?.kind !== 'declared') return null;
|
|
362
|
+
return `${LOCK_TAG} ⏳ waiting for admission of \`${workload.command}\` (weight ${workload.weight}; ${describeBlocking(blocking)}) — waiting up to ${Math.round(waitMs / 1000)}s before spawning.`;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/** The declared-run admitted line; `null` leaves the exclusive wording. */
|
|
366
|
+
export function admittedLine(workload, waited) {
|
|
367
|
+
if (workload?.kind !== 'declared') return null;
|
|
368
|
+
return `${LOCK_TAG} ✅ admitted \`${workload.command}\` (weight ${workload.weight}, waited ${waited}s).`;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** A reason worth naming over the holder pid; `null` for a plain queue. */
|
|
372
|
+
export function blockingLabel(blocking) {
|
|
373
|
+
return blocking && blocking.reason !== 'queue'
|
|
374
|
+
? describeBlocking(blocking)
|
|
375
|
+
: null;
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
/** The progress-event `blocking` field, without the holder it duplicates. */
|
|
379
|
+
export function publicBlocking(blocking, queueAhead) {
|
|
380
|
+
if (!blocking) return {};
|
|
381
|
+
const { holder: _holder, ...rest } = blocking;
|
|
382
|
+
return {
|
|
383
|
+
blocking:
|
|
384
|
+
rest.reason === 'queue' && Number.isInteger(queueAhead)
|
|
385
|
+
? { ...rest, queueAhead }
|
|
386
|
+
: rest,
|
|
387
|
+
};
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/**
|
|
391
|
+
* @param {{ reason: string, used?: number, requested?: number,
|
|
392
|
+
* capacity?: number, resource?: string, queueAhead?: number }} blocking
|
|
393
|
+
* @returns {string}
|
|
394
|
+
*/
|
|
395
|
+
export function describeBlocking(blocking) {
|
|
396
|
+
switch (blocking?.reason) {
|
|
397
|
+
case 'capacity':
|
|
398
|
+
return `capacity ${blocking.used}/${blocking.capacity} in use, ${blocking.requested} requested`;
|
|
399
|
+
case 'resource':
|
|
400
|
+
return `resource "${blocking.resource}" is held`;
|
|
401
|
+
case 'exclusive':
|
|
402
|
+
return 'an exclusive full suite holds the lock';
|
|
403
|
+
case 'queue':
|
|
404
|
+
return 'an earlier waiter is first in line';
|
|
405
|
+
case 'admission':
|
|
406
|
+
return 'another process is mid-admission';
|
|
407
|
+
default:
|
|
408
|
+
return 'blocked';
|
|
409
|
+
}
|
|
410
|
+
}
|
|
@@ -276,6 +276,12 @@ judgment that help text cannot carry.
|
|
|
276
276
|
`gates.codeReview: "overridden"` rather than `"passed"`. If you find yourself
|
|
277
277
|
reaching for it twice for the same shape of finding, the gate is
|
|
278
278
|
miscalibrated — fix the gate, not the run.
|
|
279
|
+
- `gates.codeReview: "degraded"` — not a flag but an envelope value: a
|
|
280
|
+
review surface ran yet produced no verdict (the `claude` CLI is not logged
|
|
281
|
+
in or out of quota, or its output did not parse). The PR comment lists it
|
|
282
|
+
under Degraded Gates. It is reported, not blocking — close still lands —
|
|
283
|
+
so read the diff yourself before trusting the merge. Precedence:
|
|
284
|
+
`overridden` > `degraded` > `passed`.
|
|
279
285
|
- `--max-wait-seconds <n>` — from a headless caller with no host
|
|
280
286
|
tool-invocation ceiling, to keep single-block semantics
|
|
281
287
|
without editing the consumer's config.
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,21 @@ 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.86.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.85.0...mandrel-v2.86.0) (2026-10-14)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* admit declared focused validation alongside full suites under a repo-scoped capacity budget ([#5668](https://github.com/dsj1984/mandrel/issues/5668)) ([#5669](https://github.com/dsj1984/mandrel/issues/5669)) ([318c132](https://github.com/dsj1984/mandrel/commit/318c132ed6964fcb4b6f3330ff0b3ae08cf39809))
|
|
24
|
+
|
|
25
|
+
## [2.85.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.84.0...mandrel-v2.85.0) (2026-10-13)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
* code-review held review: structured output, bounded context, and a degraded gate when no verdict is produced ([#5663](https://github.com/dsj1984/mandrel/issues/5663)) ([#5665](https://github.com/dsj1984/mandrel/issues/5665)) ([0927d4d](https://github.com/dsj1984/mandrel/commit/0927d4d3099e9cdb7e8f8491663f72f10f2042ac))
|
|
31
|
+
* stream full-suite lock wait progress live during story handoffs ([#5662](https://github.com/dsj1984/mandrel/issues/5662)) ([#5664](https://github.com/dsj1984/mandrel/issues/5664)) ([8a679cf](https://github.com/dsj1984/mandrel/commit/8a679cf248491642aa58990c8ae24532a49f286c))
|
|
32
|
+
|
|
18
33
|
## [2.84.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.83.0...mandrel-v2.84.0) (2026-10-13)
|
|
19
34
|
|
|
20
35
|
|
package/package.json
CHANGED