mandrel 2.110.0 → 2.112.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 (190) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/audit-checklists/state-machines.md +21 -0
  6. package/.agents/docs/agentrc-reference.json +23 -10
  7. package/.agents/docs/configuration.md +362 -15
  8. package/.agents/docs/execution-reference.md +11 -0
  9. package/.agents/docs/workflows.md +2 -1
  10. package/.agents/rules/ci-remediation.md +28 -4
  11. package/.agents/rules/git-conventions-reference.md +7 -0
  12. package/.agents/schemas/agentrc.schema.json +179 -13
  13. package/.agents/schemas/audit-rules.json +28 -0
  14. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  15. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  16. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  17. package/.agents/schemas/baselines/crap.schema.json +37 -10
  18. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  19. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  20. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  21. package/.agents/schemas/crap-report.schema.json +6 -5
  22. package/.agents/schemas/story-deliver-terminal.schema.json +49 -3
  23. package/.agents/schemas/story-progress.schema.json +1 -1
  24. package/.agents/schemas/validation-evidence.schema.json +2 -2
  25. package/.agents/scripts/boot-sweep.js +41 -3
  26. package/.agents/scripts/coverage-capture.js +39 -3
  27. package/.agents/scripts/coverage-ratchet.js +106 -0
  28. package/.agents/scripts/evidence-gate.js +84 -21
  29. package/.agents/scripts/file-ci-gap.js +220 -10
  30. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  31. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  32. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  33. package/.agents/scripts/lib/baseline-loader.js +4 -2
  34. package/.agents/scripts/lib/baselines/codec.js +57 -0
  35. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  36. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  37. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  38. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  39. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  40. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  41. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  42. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  43. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  44. package/.agents/scripts/lib/baselines/reader.js +36 -9
  45. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  46. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  47. package/.agents/scripts/lib/baselines/writer.js +36 -21
  48. package/.agents/scripts/lib/changed-files.js +70 -6
  49. package/.agents/scripts/lib/child-exec.js +10 -0
  50. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  51. package/.agents/scripts/lib/close-lock-events.js +8 -3
  52. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  53. package/.agents/scripts/lib/close-validation/gates.js +156 -32
  54. package/.agents/scripts/lib/close-validation/process.js +16 -7
  55. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  56. package/.agents/scripts/lib/close-validation/runner.js +160 -41
  57. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  58. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  59. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  60. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  61. package/.agents/scripts/lib/config/explain.js +5 -2
  62. package/.agents/scripts/lib/config/gates/coverage.schema.js +53 -0
  63. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  64. package/.agents/scripts/lib/config/git-roots.js +38 -4
  65. package/.agents/scripts/lib/config/handoff.js +24 -0
  66. package/.agents/scripts/lib/config/quality.js +28 -12
  67. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  68. package/.agents/scripts/lib/config-resolver.js +22 -2
  69. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  70. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  71. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  73. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  74. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  75. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  76. package/.agents/scripts/lib/coverage-capture.js +31 -0
  77. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  78. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  79. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  80. package/.agents/scripts/lib/crap-engine.js +3 -3
  81. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  82. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  83. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  84. package/.agents/scripts/lib/failure-rows.js +121 -0
  85. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  86. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  87. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  88. package/.agents/scripts/lib/gh-env.js +3 -6
  89. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  90. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  91. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  92. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  93. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  94. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  95. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  96. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  97. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  102. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  103. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  104. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
  105. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  106. package/.agents/scripts/lib/orchestration/handoff-gates.js +217 -44
  107. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  108. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  109. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
  110. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
  111. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
  112. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  113. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  114. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  115. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  116. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  117. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  118. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  119. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  120. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  121. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  122. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  123. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  124. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  125. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  127. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +17 -2
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +13 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +17 -2
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +42 -20
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -1
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +51 -15
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  140. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  141. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  142. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  143. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  144. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  145. package/.agents/scripts/lib/orchestration/single-story-close/result.js +43 -13
  146. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  147. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -2
  148. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  149. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  150. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  151. package/.agents/scripts/lib/orchestration/story-handoff.js +789 -196
  152. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  153. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  154. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  155. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  156. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  157. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  158. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  159. package/.agents/scripts/lib/suite-admission.js +20 -8
  160. package/.agents/scripts/lib/suite-sizing.js +146 -0
  161. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  162. package/.agents/scripts/merge-baseline.js +14 -3
  163. package/.agents/scripts/providers/github/comments.js +19 -3
  164. package/.agents/scripts/providers/github.js +1 -0
  165. package/.agents/scripts/review-dispositions-report.js +1 -1
  166. package/.agents/scripts/role-scope-guard.js +267 -0
  167. package/.agents/scripts/single-story-close.js +4 -4
  168. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  169. package/.agents/scripts/single-story-init.js +24 -4
  170. package/.agents/scripts/story-handoff.js +3 -3
  171. package/.agents/scripts/story-outcomes-report.js +231 -0
  172. package/.agents/scripts/story-review-compute.js +9 -5
  173. package/.agents/scripts/update-coverage-baseline.js +12 -2
  174. package/.agents/scripts/update-crap-baseline.js +9 -1
  175. package/.agents/workflows/audit-state-machines.md +213 -0
  176. package/.agents/workflows/helpers/code-review.md +63 -9
  177. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  178. package/.agents/workflows/helpers/deliver-reference.md +236 -63
  179. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  180. package/.agents/workflows/helpers/deliver-story.md +7 -2
  181. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  182. package/.agents/workflows/helpers/plan-reference.md +10 -2
  183. package/docs/CHANGELOG.md +56 -0
  184. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  185. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  186. package/lib/cli/doctor-checks/llm-review.js +2 -11
  187. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  188. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  189. package/lib/cli/registry.js +5 -0
  190. package/package.json +1 -1
@@ -14,6 +14,7 @@ import PluginSyntaxBabylon from 'escomplex-plugin-syntax-babylon/dist/PluginSynt
14
14
  import ASTWalker from 'typhonjs-ast-walker/dist/ASTWalker.js';
15
15
  import ModuleScopeControl from 'typhonjs-escomplex-commons/dist/module/report/control/ModuleScopeControl.js';
16
16
  import ModuleReport from 'typhonjs-escomplex-commons/dist/module/report/ModuleReport.js';
17
+ import { anchorOf } from './escomplex-anchor.js';
17
18
  import { install as installAstCompat } from './escomplex-ast-compat.js';
18
19
  import { describeParserMajorError } from './runtime-deps/parser-major.js';
19
20
 
@@ -103,6 +104,23 @@ function traitNewScope(syntax, node, parent) {
103
104
  return syntax.newScope.valueOf(node, parent) ?? null;
104
105
  }
105
106
 
107
+ /**
108
+ * Per method report: its enclosing method report and its call-site anchor.
109
+ * A side table, so no report gains a property (the parity corpus hashes
110
+ * them); `finalize()` keeps object identity, so lookups survive it.
111
+ */
112
+ const METHOD_SITES = new WeakMap();
113
+
114
+ /**
115
+ * @param {object} report A method report from {@link analyzeModule}.
116
+ * @returns {{parent: object|null, anchor: string|null}|undefined}
117
+ */
118
+ export function methodSiteOf(report) {
119
+ return report !== null && typeof report === 'object'
120
+ ? METHOD_SITES.get(report)
121
+ : undefined;
122
+ }
123
+
106
124
  /**
107
125
  * Event shapes are the displaced shell's: scope events lack `syntaxes`, and
108
126
  * name the scope `newScope` on entry but `scope` on exit.
@@ -118,6 +136,8 @@ function traitNewScope(syntax, node, parent) {
118
136
  function buildVisitor({ moduleReport, scopeControl, syntaxes, settings }) {
119
137
  const nodeBase = { moduleReport, scopeControl, syntaxes, settings };
120
138
  const scopeBase = { moduleReport, scopeControl, settings };
139
+ /** Every entered node; the walker pairs enter/exit, so it stays balanced. */
140
+ const ancestors = [];
121
141
  return {
122
142
  enterNode(node, parent) {
123
143
  const syntax = syntaxes[node.type];
@@ -132,12 +152,21 @@ function buildVisitor({ moduleReport, scopeControl, syntaxes, settings }) {
132
152
  if (newScope) {
133
153
  const scoped = { ...scopeBase, newScope, node, parent };
134
154
  dispatch('onModulePreScopeCreated', scoped);
135
- scopeControl.createScope(newScope);
155
+ const enclosing = scopeControl.getCurrentMethodReport() ?? null;
156
+ const report = scopeControl.createScope(newScope);
157
+ if (newScope.type === 'method') {
158
+ METHOD_SITES.set(report, {
159
+ parent: enclosing,
160
+ anchor: anchorOf(node, ancestors, ancestors.length - 1),
161
+ });
162
+ }
136
163
  dispatch('onModulePostScopeCreated', scoped);
137
164
  }
165
+ ancestors.push(node);
138
166
  return ignoreKeys;
139
167
  },
140
168
  exitNode(node, parent) {
169
+ ancestors.pop();
141
170
  const syntax = syntaxes[node.type];
142
171
  const newScope = traitNewScope(syntax, node, parent);
143
172
  if (newScope) {
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Picks the lines of a failing command's output worth quoting in a finding.
3
+ * Handoff preflight, handoff post-capture and close share it, so the three
4
+ * surfaces quote the same rows. One pass; memory is bounded by the cap.
5
+ *
6
+ * @module lib/failure-rows
7
+ */
8
+
9
+ import { stripVTControlCharacters } from 'node:util';
10
+
11
+ const DEFAULT_MAX_ROWS = 10;
12
+
13
+ const MAX_LINE_CHARS = 200;
14
+
15
+ /** Indented lines kept after a failure marker, as its rows. */
16
+ const MARKER_FOLLOW_LINES = 3;
17
+
18
+ const GATE_PREFIX = /^\[[^\]]+\] /;
19
+ const FAILURE_MARKER = /[✖✗]/;
20
+ const BIOME_HEADER = /\s*━+$/;
21
+
22
+ /** Quote-worthy lines once normalised; the biome header is handled apart. */
23
+ const SIGNATURES = Object.freeze([
24
+ /^Found \d+ (?:error|warning)s?\b/,
25
+ /^- [a-z][a-z0-9-]*: FAIL \(/,
26
+ /^↳ remedy:/,
27
+ /^· /,
28
+ /^! schema error/,
29
+ /^Totals:/,
30
+ ]);
31
+
32
+ /** A quality-preview per-file row: not the header, separator or placeholder. */
33
+ function isTableRow(line) {
34
+ return (
35
+ /^\|.*\|$/.test(line) &&
36
+ !/^\|\s*file\s*\|/.test(line) &&
37
+ !/^\|[\s|:-]+\|$/.test(line) &&
38
+ !line.includes('_(no per-file regressions)_')
39
+ );
40
+ }
41
+
42
+ /** @returns {{ raw: string, text: string }} prefix/ANSI-free line, raw keeps its indent. */
43
+ function normalise(line) {
44
+ const raw = stripVTControlCharacters(line).replace(GATE_PREFIX, '');
45
+ return { raw, text: raw.trim().slice(0, MAX_LINE_CHARS) };
46
+ }
47
+
48
+ /**
49
+ * The quotable form of a line, or `null`; the second field says whether it
50
+ * is a failure marker whose indented successors are its rows.
51
+ */
52
+ function classify(text) {
53
+ if (FAILURE_MARKER.test(text)) return { quote: text, marker: true };
54
+ if (BIOME_HEADER.test(text)) {
55
+ const quote = text.replace(BIOME_HEADER, '');
56
+ return quote ? { quote, marker: false } : null;
57
+ }
58
+ if (SIGNATURES.some((re) => re.test(text)) || isTableRow(text)) {
59
+ return { quote: text, marker: false };
60
+ }
61
+ return null;
62
+ }
63
+
64
+ /** A streaming collector: feed lines with `push`, read the quoted rows back. */
65
+ function createFailureRowCollector({ max = DEFAULT_MAX_ROWS } = {}) {
66
+ const rows = [];
67
+ const seen = new Set();
68
+ let follow = 0;
69
+ const add = (text) => {
70
+ if (rows.length >= max || seen.has(text)) return;
71
+ seen.add(text);
72
+ rows.push(text);
73
+ };
74
+ return {
75
+ push(line) {
76
+ if (rows.length >= max) return;
77
+ const { raw, text } = normalise(String(line));
78
+ if (follow > 0 && /^\s+\S/.test(raw)) {
79
+ follow -= 1;
80
+ add(text);
81
+ return;
82
+ }
83
+ follow = 0;
84
+ const hit = text ? classify(text) : null;
85
+ if (!hit) return;
86
+ add(hit.quote);
87
+ if (hit.marker) follow = MARKER_FOLLOW_LINES;
88
+ },
89
+ rows: () => [...rows],
90
+ };
91
+ }
92
+
93
+ /**
94
+ * The quoted rows of a whole output; empty means nothing parsed.
95
+ *
96
+ * @param {string} output
97
+ * @param {{ max?: number }} [opts]
98
+ * @returns {string[]}
99
+ */
100
+ export function extractFailureRows(output, opts) {
101
+ const collector = createFailureRowCollector(opts);
102
+ for (const line of String(output ?? '').split(/\r?\n/)) collector.push(line);
103
+ return collector.rows();
104
+ }
105
+
106
+ /** A finding's `: <row>; <row>` quote, `''` when nothing parsed. */
107
+ export function quoteFailureRows(output, opts) {
108
+ const rows = extractFailureRows(output, opts);
109
+ return rows.length > 0 ? `: ${rows.join('; ')}` : '';
110
+ }
111
+
112
+ /** Retains an opted-in gate's capped rows as its lines stream past `emit`. */
113
+ export function tapFailureRows(retain, emit) {
114
+ if (!retain) return { tap: emit, rowsResult: () => ({}) };
115
+ const rows = createFailureRowCollector();
116
+ const tap = (line) => {
117
+ rows.push(line);
118
+ emit(line);
119
+ };
120
+ return { tap, rowsResult: () => ({ failureRows: rows.rows() }) };
121
+ }
@@ -31,6 +31,11 @@ import {
31
31
  resolveSuiteCapacity,
32
32
  SUITE_RESERVATION_ENV,
33
33
  } from './suite-admission.js';
34
+ import {
35
+ admissionRecord,
36
+ runSizeCommand,
37
+ sizeWorkload,
38
+ } from './suite-sizing.js';
34
39
  import { defaultSleep } from './util/sleep.js';
35
40
 
36
41
  export { ADMISSION_REFUSED_EXIT_CODE, SUITE_RESERVATION_ENV };
@@ -49,6 +54,9 @@ const MIN_WAIT_MS = 300_000;
49
54
 
50
55
  const DEFAULT_POLL_MS = 2_000;
51
56
 
57
+ /** A `backfill` waiter passes no earlier waiter that has waited this long. */
58
+ const BACKFILL_WINDOW_MS = 300_000;
59
+
52
60
  /** More than one poll under 30 s, so jitter never stretches a gap past 30 s. */
53
61
  const DEFAULT_REPORT_MS = 25_000;
54
62
 
@@ -62,6 +70,8 @@ const LOCK_DEFAULTS = Object.freeze({
62
70
  ...resolveFullSuiteLockBudget(),
63
71
  pollMs: DEFAULT_POLL_MS,
64
72
  reportMs: DEFAULT_REPORT_MS,
73
+ backfillWindowMs: BACKFILL_WINDOW_MS,
74
+ runSizeFn: runSizeCommand,
65
75
  fsImpl: fs,
66
76
  env: process.env,
67
77
  nowFn: Date.now,
@@ -201,7 +211,10 @@ function consult(probe, applies) {
201
211
  * onLockOutcome?: (outcome: object) => void,
202
212
  * onLockProgress?: (progress: import('./full-suite-queue.js').LockProgress) => void,
203
213
  * rerunCommand?: string,
214
+ * spawnEnv?: Record<string, string|undefined>,
215
+ * backfillWindowMs?: number,
204
216
  * }} opts A non-`undefined` `skipIfSatisfied` return stands in for the spawn.
217
+ * `spawnEnv` (the child's own env) joins `env` for a sizing command.
205
218
  * `env` naming a live holder in this lock home spawns at once, inside it.
206
219
  * @param {(lock: { lockWaitMs: number, env: Record<string, string> }) => Promise<T>} spawn
207
220
  * `env` carries {@link SUITE_RESERVATION_ENV} for the child; merge it in.
@@ -220,17 +233,39 @@ function admitAndSpawn(opts, spawn) {
220
233
  : spawnInside(opts, inherited, spawn);
221
234
  }
222
235
 
223
- async function lockAndSpawn(opts, spawn) {
236
+ /** Unsized spawns stay synchronous up to the spawn, as before sizing existed. */
237
+ function lockAndSpawn(opts, spawn) {
238
+ return needsSizing(opts)
239
+ ? sizedOpts(opts).then((sized) => reserveAndSpawn(sized, spawn))
240
+ : reserveAndSpawn(opts, spawn);
241
+ }
242
+
243
+ async function reserveAndSpawn(opts, spawn) {
224
244
  const begun = beginLock(opts);
225
245
  try {
226
246
  const wait = await awaitTurn(opts, begun);
227
- reportOutcome(opts.onLockOutcome, wait);
247
+ reportOutcome(opts, wait);
228
248
  return await spawnOrStandIn(opts, wait, spawn, begun.attempt);
229
249
  } finally {
230
250
  begun.attempt?.release();
231
251
  }
232
252
  }
233
253
 
254
+ /** Sizing runs only on the path about to reserve, never without a lock home. */
255
+ function needsSizing(opts) {
256
+ return Boolean(opts.workload?.tiers) && lockHome(opts) !== null;
257
+ }
258
+
259
+ async function sizedOpts(opts) {
260
+ const workload = await sizeWorkload(opts.workload, {
261
+ cwd: opts.cwd,
262
+ env: { ...opts.env, ...opts.spawnEnv },
263
+ log: opts.log,
264
+ runSizeFn: opts.runSizeFn,
265
+ });
266
+ return { ...opts, workload };
267
+ }
268
+
234
269
  function inheritedMarker(opts) {
235
270
  return inheritedReservation({ ...opts, lockHomeFn: () => lockHome(opts) });
236
271
  }
@@ -259,10 +294,14 @@ function awaitTurn(opts, { attempt, lock, lockPath, blocking }) {
259
294
  }
260
295
 
261
296
  /** An I/O-error wait is no outcome; a throwing callback never costs the spawn. */
262
- function reportOutcome(onLockOutcome, wait) {
297
+ function reportOutcome({ onLockOutcome, workload }, wait) {
263
298
  if (!isFinishedWait(wait)) return;
299
+ const admission = admissionRecord(workload, wait.backfilled);
264
300
  try {
265
- onLockOutcome(lockOutcome(wait));
301
+ onLockOutcome({
302
+ ...lockOutcome(wait),
303
+ ...(admission ? { admission } : {}),
304
+ });
266
305
  } catch {}
267
306
  }
268
307
 
@@ -375,6 +414,7 @@ export function lockedCapture(
375
414
  ...lockOptions,
376
415
  cwd: captureOpts.cwd,
377
416
  log: captureOpts.log,
417
+ spawnEnv: captureOpts.env,
378
418
  skipIfSatisfied: freshnessProbe(captureOpts),
379
419
  },
380
420
  captureInLock(runCaptureFn, captureOpts),
@@ -2,7 +2,8 @@
2
2
  * full-suite-queue.js — FIFO for full-suite lock waiters (the lockfile alone
3
3
  * is first-come-first-polled). A ticket counts only while well-formed, its
4
4
  * pid alive and its mtime fresh; any I/O failure means "first in line", so
5
- * no waiter can wait forever.
5
+ * no waiter can wait forever. A ticket's body names its waiter's workload, so
6
+ * a `backfill` waiter may pass earlier ones it provably fits beside.
6
7
  */
7
8
  import crypto from 'node:crypto';
8
9
  import fs from 'node:fs';
@@ -14,10 +15,10 @@ import {
14
15
  } from './single-story-sweep/sweep-lock.js';
15
16
  import {
16
17
  admissionWaitLine,
17
- admittedLine,
18
18
  blockingLabel,
19
19
  publicBlocking,
20
20
  } from './suite-admission.js';
21
+ import { admittedLine } from './suite-sizing.js';
21
22
 
22
23
  const LOCK_TAG = '[full-suite-lock]';
23
24
 
@@ -30,10 +31,39 @@ let sequence = 0;
30
31
  * @typedef {{ dir: string, name: string, file: string }} Ticket
31
32
  */
32
33
 
34
+ /** The ticket body: a declared waiter's weight and resources, else exclusive. */
35
+ function ticketBody(workload) {
36
+ return JSON.stringify(
37
+ workload?.kind === 'declared'
38
+ ? {
39
+ kind: 'declared',
40
+ weight: workload.weight,
41
+ resources: workload.resources,
42
+ }
43
+ : { kind: 'exclusive' },
44
+ );
45
+ }
46
+
47
+ /** An empty, unreadable or malformed ticket reads as exclusive. */
48
+ function readTicketWorkload(file, fsImpl) {
49
+ try {
50
+ const body = JSON.parse(String(fsImpl.readFileSync(file, 'utf8')));
51
+ if (
52
+ body?.kind === 'declared' &&
53
+ Number.isInteger(body.weight) &&
54
+ Array.isArray(body.resources)
55
+ ) {
56
+ return body;
57
+ }
58
+ } catch {}
59
+ return { kind: 'exclusive' };
60
+ }
61
+
33
62
  /**
34
63
  * `null` when unwritable: unordered, not blocked.
35
64
  *
36
- * @param {{ lockPath: string, nowFn?: () => number, fsImpl?: object, processImpl?: object }} opts
65
+ * @param {{ lockPath: string, nowFn?: () => number, fsImpl?: object,
66
+ * processImpl?: object, workload?: object }} opts
37
67
  * @returns {Ticket|null}
38
68
  */
39
69
  function enqueueWaiter({
@@ -41,6 +71,7 @@ function enqueueWaiter({
41
71
  nowFn = Date.now,
42
72
  fsImpl = fs,
43
73
  processImpl = process,
74
+ workload,
44
75
  }) {
45
76
  const dir = `${lockPath}.queue`;
46
77
  const arrival = String(Math.max(0, Math.floor(nowFn()))).padStart(15, '0');
@@ -50,7 +81,7 @@ function enqueueWaiter({
50
81
  const file = path.join(dir, name);
51
82
  try {
52
83
  fsImpl.mkdirSync(dir, { recursive: true });
53
- fsImpl.writeFileSync(file, '');
84
+ fsImpl.writeFileSync(file, ticketBody(workload));
54
85
  } catch {
55
86
  return null;
56
87
  }
@@ -100,8 +131,8 @@ function isLiveEntry({ dir, name, staleMs, nowFn, fsImpl, killFn }) {
100
131
  }
101
132
  }
102
133
 
103
- /** Live waiters ahead of `ticket`; `null` when the queue is unreadable. */
104
- function countAhead({
134
+ /** Live ticket names ahead of `ticket`, oldest first; `null` when unreadable. */
135
+ function liveAhead({
105
136
  lockPath,
106
137
  ticket,
107
138
  staleMs,
@@ -121,7 +152,46 @@ function countAhead({
121
152
  .slice(0, own === -1 ? names.length : own)
122
153
  .filter((name) =>
123
154
  isLiveEntry({ dir, name, staleMs, nowFn, fsImpl, killFn }),
124
- ).length;
155
+ );
156
+ }
157
+
158
+ /** Live waiters ahead of `ticket`; `null` when the queue is unreadable. */
159
+ function countAhead(opts) {
160
+ return liveAhead(opts)?.length ?? null;
161
+ }
162
+
163
+ const QUEUE_BLOCK = Object.freeze({ reason: 'queue' });
164
+
165
+ /**
166
+ * Run under the admission mutex: `null` (with `passed` set) only when every
167
+ * earlier live waiter is declared, fits beside this run and shares no
168
+ * resource with it, and the oldest has waited less than the window.
169
+ */
170
+ function backfillGate(opts, ticket, state) {
171
+ const { lockPath, workload, capacity, backfillWindowMs, nowFn, fsImpl } =
172
+ opts;
173
+ const ahead = liveAhead({ ...opts, ticket });
174
+ if (!ahead?.length) return QUEUE_BLOCK;
175
+ if (nowFn() - Number(ahead[0].slice(0, 15)) >= backfillWindowMs) {
176
+ return QUEUE_BLOCK;
177
+ }
178
+ const fitsBeside = ahead.every((name) => {
179
+ const e = readTicketWorkload(path.join(`${lockPath}.queue`, name), fsImpl);
180
+ return (
181
+ e.kind === 'declared' &&
182
+ e.weight + workload.weight <= capacity &&
183
+ !e.resources.some((r) => workload.resources.includes(r))
184
+ );
185
+ });
186
+ if (!fitsBeside) return QUEUE_BLOCK;
187
+ state.passed = ahead.length;
188
+ return null;
189
+ }
190
+
191
+ function tryBackfill(opts, ticket, state) {
192
+ if (!opts.workload?.backfill)
193
+ return { acquired: false, blocking: QUEUE_BLOCK };
194
+ return opts.attempt.tryOnce(() => backfillGate(opts, ticket, state));
125
195
  }
126
196
 
127
197
  /**
@@ -207,7 +277,12 @@ export async function waitInLine(opts) {
207
277
  clock.blocking = opts.blocking ?? null;
208
278
  announceWait(opts);
209
279
  reportProgress(opts, clock, 'waiting', null);
210
- const ticket = enqueueWaiter({ lockPath, nowFn, fsImpl });
280
+ const ticket = enqueueWaiter({
281
+ lockPath,
282
+ nowFn,
283
+ fsImpl,
284
+ workload: opts.workload,
285
+ });
211
286
  try {
212
287
  const outcome = await pollForTurn(opts, ticket, clock);
213
288
  if (outcome)
@@ -288,14 +363,15 @@ async function pollForTurn(opts, ticket, clock) {
288
363
  while (nowFn() < clock.deadline) {
289
364
  await opts.sleepFn(Math.max(0, opts.pollMs));
290
365
  refreshTicket(ticket, { nowFn, fsImpl });
366
+ const state = { passed: 0 };
291
367
  const attempt = isFirstInLine({ lockPath, ticket, staleMs, nowFn, fsImpl })
292
368
  ? opts.attempt.tryOnce()
293
- : { acquired: false, blocking: { reason: 'queue' } };
369
+ : tryBackfill(opts, ticket, state);
294
370
  clock.blocking = attempt.blocking ?? null;
295
371
  if (attempt.acquired) {
296
- log(acquiredLine(opts.workload, clock.waited()));
372
+ log(acquiredLine(opts.workload, clock.waited(), state.passed));
297
373
  reportProgress(opts, clock, 'admitted', ticket);
298
- return { held: attempt, expired: false };
374
+ return { held: attempt, expired: false, backfilled: state.passed > 0 };
299
375
  }
300
376
  // A hard I/O error will not resolve by waiting; it is not an expiry.
301
377
  if (attempt.reason === 'error') return { held: null, expired: false };
@@ -304,9 +380,9 @@ async function pollForTurn(opts, ticket, clock) {
304
380
  return null;
305
381
  }
306
382
 
307
- function acquiredLine(workload, waited) {
383
+ function acquiredLine(workload, waited, passed) {
308
384
  return (
309
- admittedLine(workload, waited) ??
385
+ admittedLine(workload, waited, passed) ??
310
386
  `${LOCK_TAG} ✅ acquired the full-suite lock (waited ${waited}s).`
311
387
  );
312
388
  }