mandrel 2.87.0 → 2.89.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 (170) hide show
  1. package/.agents/README.md +29 -0
  2. package/.agents/agents/auditor.md +4 -3
  3. package/.agents/docs/agentrc-reference.json +5 -2
  4. package/.agents/docs/configuration.md +14 -8
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +24 -5
  7. package/.agents/schemas/story-deliver-terminal.schema.json +1 -1
  8. package/.agents/schemas/story-progress.schema.json +5 -0
  9. package/.agents/scripts/audit-to-stories.js +3 -2
  10. package/.agents/scripts/boot-sweep.js +3 -2
  11. package/.agents/scripts/check-arch-cycles.js +19 -41
  12. package/.agents/scripts/check-context-budget.js +16 -44
  13. package/.agents/scripts/check-cyclomatic.js +13 -37
  14. package/.agents/scripts/check-dead-exports.js +16 -46
  15. package/.agents/scripts/clean-worktrees.js +1 -6
  16. package/.agents/scripts/coverage-capture.js +32 -49
  17. package/.agents/scripts/deliver-run.js +11 -0
  18. package/.agents/scripts/diagnose-friction.js +3 -3
  19. package/.agents/scripts/lib/audit-baselines/gate-surface.js +24 -11
  20. package/.agents/scripts/lib/audit-baselines/read.js +4 -2
  21. package/.agents/scripts/lib/audit-baselines/surface-entry.js +95 -11
  22. package/.agents/scripts/lib/baselines/coverage-updater-cli.js +6 -14
  23. package/.agents/scripts/lib/baselines/crap-preview-scan.js +3 -1
  24. package/.agents/scripts/lib/baselines/crap-updater-cli.js +38 -26
  25. package/.agents/scripts/lib/baselines/duplication-scanner.js +20 -1
  26. package/.agents/scripts/lib/baselines/env-overrides.js +39 -34
  27. package/.agents/scripts/lib/baselines/kernel.js +3 -2
  28. package/.agents/scripts/lib/baselines/kinds/crap.js +50 -53
  29. package/.agents/scripts/lib/baselines/preview-gates.js +5 -1
  30. package/.agents/scripts/lib/baselines/refresh-service.js +65 -22
  31. package/.agents/scripts/lib/baselines/writer.js +5 -1
  32. package/.agents/scripts/lib/bdd-runner-detect.js +7 -10
  33. package/.agents/scripts/lib/child-exec.js +14 -1
  34. package/.agents/scripts/lib/child-stream.js +122 -0
  35. package/.agents/scripts/lib/clean-temp.js +19 -13
  36. package/.agents/scripts/lib/cli-args.js +49 -0
  37. package/.agents/scripts/lib/close-validation/gates.js +40 -9
  38. package/.agents/scripts/lib/codex/skills-projection.js +1 -12
  39. package/.agents/scripts/lib/config/gates/crap.schema.js +15 -0
  40. package/.agents/scripts/lib/config/gates/mutation.schema.js +2 -2
  41. package/.agents/scripts/lib/config/gh-config-dir.js +63 -0
  42. package/.agents/scripts/lib/config/github.js +2 -0
  43. package/.agents/scripts/lib/config/paths.js +14 -3
  44. package/.agents/scripts/lib/config/quality.js +49 -1
  45. package/.agents/scripts/lib/config-resolver.js +78 -64
  46. package/.agents/scripts/lib/config-settings-schema-delivery.js +4 -3
  47. package/.agents/scripts/lib/config-settings-schema.js +7 -0
  48. package/.agents/scripts/lib/coverage-baseline.js +2 -2
  49. package/.agents/scripts/lib/coverage-capture-affected.js +2 -1
  50. package/.agents/scripts/lib/coverage-capture-fullscope.js +2 -2
  51. package/.agents/scripts/lib/coverage-capture-incremental.js +1 -1
  52. package/.agents/scripts/lib/coverage-capture-passes.js +143 -0
  53. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  54. package/.agents/scripts/lib/coverage-capture.js +45 -15
  55. package/.agents/scripts/lib/crap-utils.js +65 -49
  56. package/.agents/scripts/lib/full-suite-lock.js +1 -10
  57. package/.agents/scripts/lib/gates/baseline-store.js +10 -0
  58. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  59. package/.agents/scripts/lib/gh-exec.js +45 -2
  60. package/.agents/scripts/lib/gh-transport.js +27 -0
  61. package/.agents/scripts/lib/git-utils.js +16 -9
  62. package/.agents/scripts/lib/maintainability-engine.js +27 -6
  63. package/.agents/scripts/lib/maintainability-utils.js +20 -2
  64. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +4 -1
  65. package/.agents/scripts/lib/orchestration/evidence-stream.js +186 -0
  66. package/.agents/scripts/lib/orchestration/file-assumptions.js +2 -19
  67. package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches-reap.js +3 -7
  68. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +34 -40
  69. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +4 -3
  70. package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js +2 -19
  71. package/.agents/scripts/lib/orchestration/pr-watch.js +1 -5
  72. package/.agents/scripts/lib/orchestration/project-meta-cache.js +17 -4
  73. package/.agents/scripts/lib/orchestration/reassert-status-column.js +1 -8
  74. package/.agents/scripts/lib/orchestration/resolve-stories.js +1 -0
  75. package/.agents/scripts/lib/orchestration/review-providers/native.js +2 -2
  76. package/.agents/scripts/lib/orchestration/single-story-close/phase-timer.js +43 -0
  77. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +37 -13
  78. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +264 -0
  79. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +68 -0
  80. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +106 -0
  81. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +43 -35
  82. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +52 -0
  83. package/.agents/scripts/lib/orchestration/single-story-close/result.js +273 -0
  84. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +68 -776
  85. package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js +20 -9
  86. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +2 -2
  87. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +20 -12
  88. package/.agents/scripts/lib/orchestration/story-handoff.js +50 -21
  89. package/.agents/scripts/lib/orchestration/story-progress.js +32 -12
  90. package/.agents/scripts/lib/orchestration/ticket-validator.js +3 -13
  91. package/.agents/scripts/lib/orchestration/verify-credit.js +4 -1
  92. package/.agents/scripts/lib/qa/resolve-selection.js +1 -8
  93. package/.agents/scripts/lib/single-story/confirm-and-land.js +33 -0
  94. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +43 -11
  95. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +130 -30
  96. package/.agents/scripts/lib/skills/parse-skill.js +1 -4
  97. package/.agents/scripts/lib/story-body/story-body.js +12 -1
  98. package/.agents/scripts/lib/suite-admission.js +3 -11
  99. package/.agents/scripts/lib/temp-retention.js +25 -11
  100. package/.agents/scripts/lib/test-run-credit.js +2 -5
  101. package/.agents/scripts/lib/transpile.js +193 -31
  102. package/.agents/scripts/lib/util/paths.js +31 -0
  103. package/.agents/scripts/lib/util/sleep.js +15 -0
  104. package/.agents/scripts/lib/validation-evidence.js +29 -3
  105. package/.agents/scripts/lib/wave-runner/live-probe.js +24 -0
  106. package/.agents/scripts/lib/workers/crap-worker.js +23 -12
  107. package/.agents/scripts/lib/workers/maintainability-report-worker.js +18 -12
  108. package/.agents/scripts/lib/workflow-closure.js +1 -8
  109. package/.agents/scripts/notify.js +83 -90
  110. package/.agents/scripts/plan-context.js +8 -4
  111. package/.agents/scripts/providers/github/auth.js +14 -30
  112. package/.agents/scripts/providers/github/blocked-by-add.js +11 -27
  113. package/.agents/scripts/providers/github/compose.js +1 -0
  114. package/.agents/scripts/providers/github/gh-token-diagnostics.js +130 -0
  115. package/.agents/scripts/providers/github/identity.js +158 -0
  116. package/.agents/scripts/providers/github/issues.js +2 -2
  117. package/.agents/scripts/providers/github/mappers.js +16 -19
  118. package/.agents/scripts/providers/github/projects-v2-graphql.js +4 -36
  119. package/.agents/scripts/providers/github/request-helpers.js +44 -0
  120. package/.agents/scripts/providers/github/sub-issue-add.js +11 -28
  121. package/.agents/scripts/providers/github.js +10 -2
  122. package/.agents/scripts/quality-preview.js +6 -19
  123. package/.agents/scripts/single-story-confirm-merge.js +8 -20
  124. package/.agents/scripts/single-story-init.js +0 -1
  125. package/.agents/scripts/stories-wave-tick.js +60 -46
  126. package/.agents/scripts/story-handoff.js +2 -23
  127. package/.agents/scripts/story-review-compute.js +3 -22
  128. package/.agents/scripts/sync-claude-agents.js +1 -12
  129. package/.agents/scripts/sync-claude-commands.js +1 -12
  130. package/.agents/scripts/update-crap-baseline.js +11 -20
  131. package/.agents/scripts/update-ticket-state.js +44 -45
  132. package/.agents/templates/docs/audit-sweep-runbook.md +1 -1
  133. package/.agents/workflows/audit-accessibility.md +1 -1
  134. package/.agents/workflows/audit-adrs.md +1 -1
  135. package/.agents/workflows/audit-architecture.md +1 -1
  136. package/.agents/workflows/audit-baselines.md +9 -4
  137. package/.agents/workflows/audit-clean-code.md +1 -1
  138. package/.agents/workflows/audit-data-model.md +1 -1
  139. package/.agents/workflows/audit-dependencies.md +1 -1
  140. package/.agents/workflows/audit-devops.md +1 -1
  141. package/.agents/workflows/audit-documentation.md +1 -1
  142. package/.agents/workflows/audit-exceptions.md +2 -2
  143. package/.agents/workflows/audit-mobile.md +1 -1
  144. package/.agents/workflows/audit-navigability.md +1 -1
  145. package/.agents/workflows/audit-performance.md +1 -1
  146. package/.agents/workflows/audit-privacy.md +1 -1
  147. package/.agents/workflows/audit-quality.md +1 -1
  148. package/.agents/workflows/audit-security.md +1 -1
  149. package/.agents/workflows/audit-seo.md +1 -1
  150. package/.agents/workflows/audit-sre.md +1 -1
  151. package/.agents/workflows/audit-to-stories.md +9 -7
  152. package/.agents/workflows/audit-ux-ui.md +1 -1
  153. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  154. package/.agents/workflows/helpers/deliver-digest.md +4 -5
  155. package/.agents/workflows/helpers/deliver-story-reference.md +4 -4
  156. package/.agents/workflows/mandrel-deliver.md +3 -1
  157. package/README.md +6 -3
  158. package/docs/CHANGELOG.md +42 -0
  159. package/lib/cli/doctor-checks/codex.js +240 -0
  160. package/lib/cli/doctor-checks/merge-driver.js +79 -0
  161. package/lib/cli/doctor-checks/payload.js +201 -0
  162. package/lib/cli/doctor-checks/read-json.js +16 -0
  163. package/lib/cli/doctor-checks/runtime-deps.js +146 -0
  164. package/lib/cli/doctor-checks/spawn.js +18 -0
  165. package/lib/cli/doctor-checks/sync-parity.js +205 -0
  166. package/lib/cli/doctor-checks/test-credit-path.js +270 -0
  167. package/lib/cli/doctor-checks/toolchain.js +137 -0
  168. package/lib/cli/doctor-checks/version-current.js +82 -0
  169. package/lib/cli/registry.js +40 -1330
  170. package/package.json +1 -1
@@ -3,18 +3,27 @@
3
3
  *
4
4
  * Best-effort cross-process lockfile (atomic `wx` create) for the merged-branch
5
5
  * sweep. Never load-bearing: a contended caller skips or proceeds. A live
6
- * holder is never mistaken for a crashed one: it heartbeats its mtime, a
7
- * stale-breaker removes only the exact file it observed (dev/ino/mtime), and
8
- * release unlinks only a lockfile still stamped with its owner.
6
+ * holder is never mistaken for a crashed one: it heartbeats its mtime. Only
7
+ * break and release remove the lockfile, each under a short `.break` mutex
8
+ * that re-checks identity/owner first, so no removal races another.
9
9
  */
10
10
 
11
11
  import fs from 'node:fs';
12
12
  import path from 'node:path';
13
+ import { defaultSleep } from '../util/sleep.js';
13
14
 
14
15
  const DEFAULT_TIMEOUT_MS = 60_000;
15
16
 
16
17
  const MIN_HEARTBEAT_MS = 1_000;
17
18
 
19
+ // A crashed breaker's mutex is reclaimed past this; a live one holds it for
20
+ // microseconds.
21
+ const BREAK_MUTEX_STALE_MS = 10_000;
22
+
23
+ const RELEASE_MUTEX_TRIES = 25;
24
+
25
+ const RELEASE_MUTEX_SPIN_MS = 2;
26
+
18
27
  // Three refreshes per staleness window: two missed refreshes (stalled loop,
19
28
  // slow disk) still do not make a live holder look dead.
20
29
  const HEARTBEAT_DIVISOR = 3;
@@ -148,6 +157,11 @@ export function isLockStale(mtime, nowMs, timeoutMs) {
148
157
  */
149
158
  function tryCreateLock(lockPath, ownerId, fsImpl = fs) {
150
159
  fsImpl.mkdirSync(path.dirname(lockPath), { recursive: true });
160
+ return tryCreateFile(lockPath, ownerId, fsImpl);
161
+ }
162
+
163
+ /** No `mkdir`: a mutex beside a reaped lockfile must not resurrect its dir. */
164
+ function tryCreateFile(lockPath, ownerId, fsImpl) {
151
165
  let fd;
152
166
  try {
153
167
  fd = fsImpl.openSync(lockPath, 'wx');
@@ -180,6 +194,7 @@ function tryCreateLock(lockPath, ownerId, fsImpl = fs) {
180
194
  * @param {Function} [opts.clearIntervalFn]
181
195
  * @param {Function} [opts.killFn] Holder liveness probe seam.
182
196
  * @param {object} [opts.processImpl] Seam for release-on-signal.
197
+ * @param {(event: LockEvent) => void} [opts.onLockEvent] Theft observer.
183
198
  * @returns {{ acquired: true, release: () => void, ownerId: string }
184
199
  * | { acquired: false, reason: 'contended' | 'error', detail?: string }}
185
200
  */
@@ -194,6 +209,7 @@ export function acquireSweepLock({
194
209
  clearIntervalFn = clearInterval,
195
210
  killFn,
196
211
  processImpl = process,
212
+ onLockEvent = reportLockEvent,
197
213
  } = {}) {
198
214
  if (typeof lockPath !== 'string' || lockPath.length === 0) {
199
215
  return {
@@ -213,6 +229,7 @@ export function acquireSweepLock({
213
229
  clearIntervalFn,
214
230
  killFn,
215
231
  processImpl,
232
+ onLockEvent,
216
233
  };
217
234
  try {
218
235
  if (
@@ -232,7 +249,7 @@ export function acquireSweepLock({
232
249
  }
233
250
 
234
251
  /**
235
- * `true` only when this call removed the exact stale file it observed and won
252
+ * `true` only when this call broke the exact stale file it observed and won
236
253
  * the re-create, so concurrent breakers yield one acquisition.
237
254
  *
238
255
  * @param {{ lockPath: string, ownerId: string, fsImpl: object, nowFn: () => number }} holder
@@ -251,7 +268,7 @@ function tryStaleTakeover(
251
268
  return false;
252
269
  }
253
270
  return (
254
- breakStaleLock(lockPath, observed, fsImpl) &&
271
+ breakStaleLock({ lockPath, fsImpl, nowFn }, observed) &&
255
272
  tryCreateLock(lockPath, ownerId, fsImpl)
256
273
  );
257
274
  }
@@ -279,20 +296,56 @@ function isHolderStale({
279
296
  }
280
297
 
281
298
  /**
282
- * Unlink only if the file is still the observed instance; `false` means
283
- * someone else owns it now.
299
+ * Under the break mutex nothing else can remove the lockfile and a creator
300
+ * cannot replace a present one, so the identity re-read holds until the
301
+ * unlink. `false` means someone else owns it now, or another breaker is mid-break.
284
302
  *
285
- * @param {string} lockPath
303
+ * @param {{ lockPath: string, fsImpl: object, nowFn: () => number }} where
286
304
  * @param {ReturnType<typeof readLockIdentity>} observed
287
- * @param {object} fsImpl
288
305
  * @returns {boolean}
289
306
  */
290
- function breakStaleLock(lockPath, observed, fsImpl) {
291
- if (!sameLockIdentity(observed, readLockIdentity(lockPath, fsImpl))) {
292
- return false;
307
+ function breakStaleLock(where, observed) {
308
+ return Boolean(withBreakMutex(where, () => unlinkIfSame(where, observed)));
309
+ }
310
+
311
+ function unlinkIfSame({ lockPath, fsImpl }, observed) {
312
+ const same = sameLockIdentity(observed, readLockIdentity(lockPath, fsImpl));
313
+ return same && unlinkQuietly(lockPath, fsImpl);
314
+ }
315
+
316
+ /**
317
+ * Runs `fn` holding `<lockPath>.break`.
318
+ *
319
+ * @returns {*} `fn()`'s result, or `null` when the mutex is busy.
320
+ */
321
+ function withBreakMutex({ lockPath, fsImpl, nowFn = Date.now }, fn) {
322
+ const mutexPath = `${lockPath}.break`;
323
+ if (!takeBreakMutex(mutexPath, fsImpl, nowFn)) return null;
324
+ try {
325
+ return fn();
326
+ } finally {
327
+ unlinkQuietly(mutexPath, fsImpl);
293
328
  }
329
+ }
330
+
331
+ function takeBreakMutex(mutexPath, fsImpl, nowFn) {
332
+ return (
333
+ tryCreateFile(mutexPath, 'break', fsImpl) ||
334
+ reclaimStaleMutex(mutexPath, fsImpl, nowFn)
335
+ );
336
+ }
337
+
338
+ function reclaimStaleMutex(mutexPath, fsImpl, nowFn) {
339
+ const mtime = readLockMtime(mutexPath, fsImpl);
340
+ if (!isLockStale(mtime, nowFn(), BREAK_MUTEX_STALE_MS)) return false;
341
+ unlinkQuietly(mutexPath, fsImpl);
342
+ return tryCreateFile(mutexPath, 'break', fsImpl);
343
+ }
344
+
345
+ /** @returns {boolean} whether the unlink landed. */
346
+ function unlinkQuietly(file, fsImpl) {
294
347
  try {
295
- fsImpl.unlinkSync(lockPath);
348
+ fsImpl.unlinkSync(file);
296
349
  return true;
297
350
  } catch {
298
351
  return false;
@@ -300,14 +353,44 @@ function breakStaleLock(lockPath, observed, fsImpl) {
300
353
  }
301
354
 
302
355
  /**
303
- * Refuses a lockfile no longer ours, or we would keep a thief's lock alive.
356
+ * @typedef {{ type: 'lock-lost', lockPath: string, ownerId: string,
357
+ * currentOwner: string|null }} LockEvent
358
+ */
359
+
360
+ /** Default theft observer: one stderr line, never a throw. */
361
+ function reportLockEvent({ lockPath, ownerId, currentOwner }) {
362
+ try {
363
+ process.stderr.write(
364
+ `[sweep-lock] ⚠ lost ${lockPath} while holding it as ${ownerId} (now ${currentOwner ?? 'absent'}).\n`,
365
+ );
366
+ } catch {}
367
+ }
368
+
369
+ /**
370
+ * Refuses (and reports) a lockfile no longer ours.
304
371
  *
305
- * @param {{ lockPath: string, ownerId: string, fsImpl?: object, nowFn?: () => number }} holder
372
+ * @param {{ lockPath: string, ownerId: string, fsImpl?: object,
373
+ * nowFn?: () => number, onLockEvent?: (event: LockEvent) => void }} holder
306
374
  * @returns {boolean} `true` when the refresh landed; `false` when the lock is
307
375
  * no longer ours (the caller stops heartbeating).
308
376
  */
309
- function refreshLockSync({ lockPath, ownerId, fsImpl = fs, nowFn = Date.now }) {
310
- if (readLockOwner(lockPath, fsImpl) !== ownerId) return false;
377
+ function refreshLockSync(holder) {
378
+ const { lockPath, ownerId, fsImpl = fs } = holder;
379
+ const currentOwner = readLockOwner(lockPath, fsImpl);
380
+ if (currentOwner !== ownerId) {
381
+ emitLockLost(holder, currentOwner);
382
+ return false;
383
+ }
384
+ return touchLock(holder);
385
+ }
386
+
387
+ function emitLockLost({ lockPath, ownerId, onLockEvent }, currentOwner) {
388
+ try {
389
+ onLockEvent?.({ type: 'lock-lost', lockPath, ownerId, currentOwner });
390
+ } catch {}
391
+ }
392
+
393
+ function touchLock({ lockPath, fsImpl = fs, nowFn = Date.now }) {
311
394
  try {
312
395
  const stamp = new Date(nowFn());
313
396
  fsImpl.utimesSync(lockPath, stamp, stamp);
@@ -347,14 +430,38 @@ function startHeartbeat(holder) {
347
430
  * @param {object} fsImpl
348
431
  */
349
432
  function unlinkIfOwned(lockPath, ownerId, fsImpl) {
350
- if (readLockOwner(lockPath, fsImpl) !== ownerId) return;
433
+ const isOwn = () => readLockOwner(lockPath, fsImpl) === ownerId;
434
+ const removeOwn = () => isOwn() && unlinkQuietly(lockPath, fsImpl);
435
+ if (isOwn()) releaseOwned(lockPath, fsImpl, removeOwn);
436
+ }
437
+
438
+ /** Fail open: a wedged mutex must not strand our lock until it reads stale. */
439
+ function releaseOwned(lockPath, fsImpl, removeOwn) {
440
+ if (!releaseUnderMutex(lockPath, fsImpl, removeOwn)) removeOwn();
441
+ }
442
+
443
+ function releaseUnderMutex(lockPath, fsImpl, removeOwn) {
444
+ for (let tries = 0; tries < RELEASE_MUTEX_TRIES; tries += 1) {
445
+ if (guardedRelease(lockPath, fsImpl, removeOwn)) return true;
446
+ sleepSync(RELEASE_MUTEX_SPIN_MS);
447
+ }
448
+ return false;
449
+ }
450
+
451
+ /** `true` once the release ran under the break mutex (or could not take it). */
452
+ function guardedRelease(lockPath, fsImpl, removeOwn) {
351
453
  try {
352
- fsImpl.unlinkSync(lockPath);
454
+ return withBreakMutex({ lockPath, fsImpl }, removeOwn) !== null;
353
455
  } catch {
354
- // Already gone.
456
+ removeOwn();
457
+ return true;
355
458
  }
356
459
  }
357
460
 
461
+ function sleepSync(ms) {
462
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
463
+ }
464
+
358
465
  function buildAcquired(holder) {
359
466
  const { lockPath, ownerId, fsImpl, processImpl = process } = holder;
360
467
  const stopHeartbeat = startHeartbeat(holder);
@@ -422,16 +529,6 @@ function attachSignalRelease(processImpl, release) {
422
529
  const DEFAULT_WAIT_MS = 8_000;
423
530
  const DEFAULT_POLL_MS = 150;
424
531
 
425
- /**
426
- * @param {number} ms
427
- * @returns {Promise<void>}
428
- */
429
- function defaultSleep(ms) {
430
- return new Promise((resolve) => {
431
- setTimeout(resolve, ms);
432
- });
433
- }
434
-
435
532
  /**
436
533
  * Polls {@link acquireSweepLock} up to `waitMs` — a collision damper for the
437
534
  * post-land tail, not mutual exclusion: on exhaustion the caller proceeds
@@ -449,6 +546,7 @@ function defaultSleep(ms) {
449
546
  * @param {number} [opts.heartbeatMs]
450
547
  * @param {Function} [opts.setIntervalFn]
451
548
  * @param {Function} [opts.clearIntervalFn]
549
+ * @param {(event: LockEvent) => void} [opts.onLockEvent]
452
550
  * @returns {Promise<{ acquired: true, release: () => void, ownerId: string }
453
551
  * | { acquired: false, reason: 'contended-after-wait' | 'error', detail?: string }>}
454
552
  */
@@ -466,6 +564,7 @@ export async function acquireLockWithWait({
466
564
  clearIntervalFn = clearInterval,
467
565
  killFn,
468
566
  processImpl,
567
+ onLockEvent,
469
568
  } = {}) {
470
569
  const deadline = nowFn() + Math.max(0, waitMs);
471
570
  for (;;) {
@@ -480,6 +579,7 @@ export async function acquireLockWithWait({
480
579
  clearIntervalFn,
481
580
  killFn,
482
581
  processImpl,
582
+ onLockEvent,
483
583
  });
484
584
  if (res.acquired) return res;
485
585
  if (res.reason === 'error') return res;
@@ -7,6 +7,7 @@
7
7
  import fs from 'node:fs';
8
8
  import path from 'node:path';
9
9
  import yaml from 'js-yaml';
10
+ import { toPosix } from '../util/paths.js';
10
11
 
11
12
  const FRONTMATTER_DELIMITER = '---';
12
13
  const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
@@ -29,10 +30,6 @@ function resolveRepoRoot(absoluteSkillPath) {
29
30
  return path.resolve(path.dirname(absoluteSkillPath), '..', '..', '..', '..');
30
31
  }
31
32
 
32
- function toPosix(p) {
33
- return p.split(path.sep).join('/');
34
- }
35
-
36
33
  /** Indices match the file's lines, so 1-based line numbers report verbatim. */
37
34
  function splitLines(src) {
38
35
  return src.split(/\r\n|\n/);
@@ -123,6 +123,17 @@ const AC_PREFIX_RE = /^AC-\d+[a-z]?:\s*/i;
123
123
  const WIDE_MARKER_LINE_RE = /^>\s*\*\*Wide:\*\*/;
124
124
  const AUTHORED_MARKER_LINE_RE = /^\s*>\s*🏷️\s+Authored with Mandrel\b/;
125
125
  const META_BLOCK_RE = /<!--\s*meta:[\s\S]*?-->/;
126
+ // Provenance and plan-story markers persist appends after the last section
127
+ // can land in a path list; a whole-line comment is never a path bullet.
128
+ const WHOLE_LINE_COMMENT_RE = /^\s*<!--.*-->\s*$/;
129
+
130
+ /**
131
+ * @param {string} line
132
+ * @returns {boolean}
133
+ */
134
+ function isNotCommentLine(line) {
135
+ return !WHOLE_LINE_COMMENT_RE.test(line);
136
+ }
126
137
 
127
138
  /**
128
139
  * Parse one `changes` / `references` bullet: bare path (`assumption: null`),
@@ -432,7 +443,7 @@ function parseTextBlockSection(lines) {
432
443
  */
433
444
  function parsePathEntrySection(lines, warnings) {
434
445
  const entries = [];
435
- for (const line of lines) {
446
+ for (const line of lines.filter(isNotCommentLine)) {
436
447
  const stripped = stripListMarker(line);
437
448
  if (!stripped) continue;
438
449
  const entry = parsePathEntry(stripped, warnings);
@@ -9,7 +9,7 @@
9
9
  * undeclared spawn is exclusive: it takes the legacy lockfile (so older
10
10
  * Mandrel versions still queue behind it) and drains every reservation first.
11
11
  * Check-then-reserve runs under a short admission mutex, so two processes can
12
- * never both take the last slot.
12
+ * never both take the last slot; the exclusive drain check takes it too.
13
13
  */
14
14
  import crypto from 'node:crypto';
15
15
  import os from 'node:os';
@@ -306,7 +306,8 @@ function createDeclaredAttempt(opts) {
306
306
 
307
307
  /**
308
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.
309
+ * so nothing new is admitted) until every live reservation has drained —
310
+ * always under the mutex, or a declared run mid-admission is missed.
310
311
  *
311
312
  * @param {{ lockPath: string, capacity: number, staleMs: number,
312
313
  * fsImpl: object, nowFn: () => number, killFn?: Function,
@@ -336,7 +337,6 @@ function createExclusiveAttempt(opts) {
336
337
  if (!first.acquired) return first;
337
338
  held = first;
338
339
  }
339
- if (!hasReservations(opts)) return held;
340
340
  const verdict = underAdmissionMutex(opts, drained);
341
341
  return verdict.reason === 'error' ? held : verdict;
342
342
  };
@@ -346,14 +346,6 @@ function createExclusiveAttempt(opts) {
346
346
  };
347
347
  }
348
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
349
  const LOCK_TAG = '[full-suite-lock]';
358
350
 
359
351
  /** The declared-run wait line; `null` leaves the exclusive wording. */
@@ -61,6 +61,8 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
61
61
  const STORY_DIR_PATTERN = /^story-(\d+)$/;
62
62
  const TRAILING_ID_PATTERN = /-(\d+)$/;
63
63
  const AUDIT_STORY_PATTERN = /^audit-story-(\d+)-/;
64
+ /** Lens reports' own folder under `audits/` (`auditResultsDir`). */
65
+ const AUDIT_RESULTS_DIRNAME = 'audit-results';
64
66
  /** Per-run temp tree holding `stories/story-<id>/` children. */
65
67
  const RUN_DIR_PATTERN = /^run-\d+$/;
66
68
 
@@ -187,21 +189,33 @@ async function scanValidationEvidence(tempRoot, fsp) {
187
189
  return entries;
188
190
  }
189
191
 
190
- /** `<tempRoot>/audits/*`; `audit-story-<id>-*` is Story-keyed, rest age-floored. */
192
+ /** One `auditResults` entry; `audit-story-<id>-*` is Story-keyed, rest age-floored. */
193
+ function auditEntry(fsp, dir, name) {
194
+ const match = AUDIT_STORY_PATTERN.exec(name);
195
+ return makeEntry(
196
+ fsp,
197
+ path.join(dir, name),
198
+ 'auditResults',
199
+ match ? Number(match[1]) : null,
200
+ );
201
+ }
202
+
203
+ /**
204
+ * `<tempRoot>/audits/*`, with `audits/audit-results/` walked per report —
205
+ * reaping that folder wholesale would take fresh reports with stale ones.
206
+ */
191
207
  async function scanAuditResults(tempRoot, fsp) {
192
208
  const dir = path.join(tempRoot, 'audits');
193
- const entries = [];
209
+ const resultsDir = path.join(dir, AUDIT_RESULTS_DIRNAME);
210
+ const pending = [];
194
211
  for (const dirent of await safeReaddir(fsp, dir)) {
195
- const match = AUDIT_STORY_PATTERN.exec(dirent.name);
196
- const entry = await makeEntry(
197
- fsp,
198
- path.join(dir, dirent.name),
199
- 'auditResults',
200
- match ? Number(match[1]) : null,
201
- );
202
- if (entry) entries.push(entry);
212
+ if (dirent.name === AUDIT_RESULTS_DIRNAME && dirent.isDirectory()) continue;
213
+ pending.push(auditEntry(fsp, dir, dirent.name));
203
214
  }
204
- return entries;
215
+ for (const dirent of await safeReaddir(fsp, resultsDir)) {
216
+ pending.push(auditEntry(fsp, resultsDir, dirent.name));
217
+ }
218
+ return (await Promise.all(pending)).filter(Boolean);
205
219
  }
206
220
 
207
221
  /** `<tempRoot>/plan-<slug>/`: predates its Stories, so age is the only signal. */
@@ -14,7 +14,7 @@ import {
14
14
  resolveTestGateArgv,
15
15
  } from './close-validation/commands.js';
16
16
  import { resolveConfig } from './config-resolver.js';
17
- import { gitSpawn as defaultGitSpawn } from './git-utils.js';
17
+ import { gitSpawn as defaultGitSpawn, parseStoryBranch } from './git-utils.js';
18
18
  import {
19
19
  recordPass as defaultRecordPass,
20
20
  shouldSkip as defaultShouldSkip,
@@ -77,10 +77,7 @@ function gitLine(gitSpawnFn, cwd, args) {
77
77
  * @returns {number|null}
78
78
  */
79
79
  export function storyIdFromBranch(branch) {
80
- const match = /^story-(\d+)$/.exec(branch ?? '');
81
- if (!match) return null;
82
- const id = Number.parseInt(match[1], 10);
83
- return Number.isInteger(id) && id > 0 ? id : null;
80
+ return parseStoryBranch(branch);
84
81
  }
85
82
 
86
83
  /**