mandrel 2.106.0 → 2.108.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 (39) hide show
  1. package/.agents/docs/configuration.md +32 -0
  2. package/.agents/schemas/agentrc.schema.json +38 -0
  3. package/.agents/schemas/story-deliver-terminal.schema.json +4 -0
  4. package/.agents/scripts/evidence-gate.js +2 -2
  5. package/.agents/scripts/lib/audit-suite/selector.js +13 -5
  6. package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
  7. package/.agents/scripts/lib/close-validation/process.js +1 -1
  8. package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
  9. package/.agents/scripts/lib/full-suite-lock.js +81 -8
  10. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  11. package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
  12. package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
  13. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  14. package/.agents/scripts/lib/orchestration/code-review.js +77 -13
  15. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
  16. package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
  17. package/.agents/scripts/lib/orchestration/review-history.js +182 -0
  18. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
  19. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +5 -4
  20. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
  21. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +15 -8
  22. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
  23. package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
  24. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
  25. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
  27. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
  28. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
  29. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
  30. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  31. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
  32. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
  33. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
  34. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
  35. package/.agents/scripts/lib/suite-admission.js +45 -3
  36. package/.agents/scripts/review-dispositions-report.js +129 -0
  37. package/.agents/workflows/helpers/code-review.md +53 -0
  38. package/docs/CHANGELOG.md +22 -0
  39. package/package.json +1 -1
@@ -248,6 +248,9 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
248
248
  | `codeReview` | No | `object` | — | Review-provider chain and on-branch remediation threshold for the /mandrel-deliver code-review ceremony. |
249
249
  | `codeReview.providers[]` | No | `array<object>` | `[{"name":"native"},{"name":"llm-review","scopes":["story"],"optional":true}]` | Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `llm-review` — the first available of `code-review` (a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge) and `codex` (`codex exec`), so a host with both CLIs runs one LLM review and a host with neither skips it. Pin `code-review` or `codex` to choose the CLI. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
250
250
  | `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /mandrel-deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
251
+ | `codeReview.sensitivePaths` | No | `object<map>` | — | The project's own sensitive-path classes, merged additively over the shipped `audit-rules.json` `sensitivePaths`: a class named like a shipped one appends its patterns to it, a new name adds a class, and no shipped class or pattern can be removed or narrowed. A changed file matching any class derives a `high` change level, which drives both code-review depth (`deep`, never `light`) and plan-time routing. Patterns are picomatch globs matched with `dot: true`. |
252
+ | `codeReview.guidanceFile` | No | `string` | — | Project review guidance, a path relative to the project root. Unset, a root `REVIEW.md` is used when present; an absent file is a no-op. Its text is rendered into every LLM review provider's prompt after the framework's severity and anti-gaming rules, and over 8,000 characters is truncated with a degradation. Guidance may add failure classes and paths worth skipping but cannot lower a severity rule, excuse a `shortcut:`, or change the output shape. |
253
+ | `codeReview.skipPaths` | No | `array<string>` | — | Picomatch globs (`dot: true`) whose findings are dropped after grounding and before severity is counted; the report states how many were dropped. A finding is dropped when its file, or every instance file, matches. Only config sets skip paths: guidance prose cannot silence a finding. |
251
254
  | `refactorStage` | No | `object` | — | Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics. |
252
255
  | `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
253
256
  | `acceptanceEval` | No | `object` | — | Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds (0 = scored once, no redraft), then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the scoring pass is a hard cutover (always on). |
@@ -400,6 +403,35 @@ A config still carrying the retired key is a hard validation failure; the
400
403
  reporters. `coverage-capture.js` fails a green run that leaves no artifact
401
404
  there (and writes no capture stamp), and a full-scope coverage or CRAP
402
405
  refresh with no artifact exits non-zero naming the path.
406
+ - **Admission for a script you run by hand.** Every suite spawn Mandrel
407
+ admits under `execution.fullSuiteLock` carries `MANDREL_SUITE_RESERVATION`,
408
+ the absolute path of the lockfile or reservation it holds, and every
409
+ descendant inherits it. A consumer script that may also be started by hand
410
+ (say `test:coverage:affected`, run from an agent shell) admits itself
411
+ through the materialized lock library rather than bypassing admission:
412
+
413
+ ```js
414
+ import { withSuiteAdmission } from '../.agents/scripts/lib/full-suite-lock.js';
415
+
416
+ const code = await withSuiteAdmission(
417
+ { argv: ['pnpm', 'run', 'test:coverage:affected'], cwd: process.cwd() },
418
+ ({ env }) => runSuite({ env: { ...process.env, ...env } }),
419
+ );
420
+ process.exit(code);
421
+ ```
422
+
423
+ Pass `argv` exactly as it appears in `execution.workloads[]`. `env` (default
424
+ `process.env`), `log` and `config` (default: resolved from `cwd`) are
425
+ optional. When the environment already names a live reservation in this
426
+ repository's lock home, the callback runs at once inside it and nothing new
427
+ is reserved. Otherwise, including when that reservation's file is gone,
428
+ its holder has died or its heartbeat is stale, the run queues for its
429
+ declared workload, or exclusively when the argv is undeclared, exactly as a
430
+ Mandrel caller would. The callback's `env` names the reservation that
431
+ admitted it; merge it into the child's environment. The helper resolves to
432
+ the callback's result, `75` when the wait expires, or `78` when the
433
+ declared weight exceeds `capacity`. With `MANDREL_FULL_SUITE_LOCK=0` or
434
+ `fullSuiteLock: false` it calls the callback directly with an empty `env`.
403
435
  - **Duplication needs jscpd.** The duplication gate scans with `jscpd` 4, an
404
436
  **optional peer dependency** of `mandrel`: a project that enables
405
437
  `quality.gates.duplication` installs it itself — `npm i -D jscpd@^4`.
@@ -1394,6 +1394,44 @@
1394
1394
  "enum": ["high", "medium"],
1395
1395
  "description": "Severity threshold for on-branch remediation in /mandrel-deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag.",
1396
1396
  "default": "medium"
1397
+ },
1398
+ "sensitivePaths": {
1399
+ "type": "object",
1400
+ "description": "The project's own sensitive-path classes, merged additively over the shipped `audit-rules.json` `sensitivePaths`: a class named like a shipped one appends its patterns to it, a new name adds a class, and no shipped class or pattern can be removed or narrowed. A changed file matching any class derives a `high` change level, which drives both code-review depth (`deep`, never `light`) and plan-time routing. Patterns are picomatch globs matched with `dot: true`.",
1401
+ "propertyNames": {
1402
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
1403
+ },
1404
+ "additionalProperties": {
1405
+ "type": "object",
1406
+ "required": ["filePatterns"],
1407
+ "properties": {
1408
+ "description": {
1409
+ "type": "string"
1410
+ },
1411
+ "filePatterns": {
1412
+ "type": "array",
1413
+ "minItems": 1,
1414
+ "items": {
1415
+ "type": "string",
1416
+ "minLength": 1
1417
+ }
1418
+ }
1419
+ },
1420
+ "additionalProperties": false
1421
+ }
1422
+ },
1423
+ "guidanceFile": {
1424
+ "type": "string",
1425
+ "minLength": 1,
1426
+ "description": "Project review guidance, a path relative to the project root. Unset, a root `REVIEW.md` is used when present; an absent file is a no-op. Its text is rendered into every LLM review provider's prompt after the framework's severity and anti-gaming rules, and over 8,000 characters is truncated with a degradation. Guidance may add failure classes and paths worth skipping but cannot lower a severity rule, excuse a `shortcut:`, or change the output shape."
1427
+ },
1428
+ "skipPaths": {
1429
+ "type": "array",
1430
+ "items": {
1431
+ "type": "string",
1432
+ "minLength": 1
1433
+ },
1434
+ "description": "Picomatch globs (`dot: true`) whose findings are dropped after grounding and before severity is counted; the report states how many were dropped. A finding is dropped when its file, or every instance file, matches. Only config sets skip paths: guidance prose cannot silence a finding."
1397
1435
  }
1398
1436
  },
1399
1437
  "additionalProperties": false
@@ -105,6 +105,10 @@
105
105
  },
106
106
  "refCleanup": { "type": "boolean" },
107
107
  "baseFastForward": { "type": "boolean" },
108
+ "reviewDispositions": {
109
+ "type": "boolean",
110
+ "description": "Each finding the Story-scope reviews raised was recorded to the local review-dispositions ledger before the temp purge reaped the review history. No history, or a Story already recorded, reports true. Only a ledger failure reports false, and like every tail step that degrades the report, never the land."
111
+ },
108
112
  "tempPurge": {
109
113
  "type": "boolean",
110
114
  "description": "Story #4794 — the merged Story's spent temp artifacts (gate transcripts, validation evidence) were purged under delivery.tempRetention. A disabled policy reports true: the operator turned the purge off, so doing nothing IS the correct outcome. Only a real failure — an unreadable temp root, an undeletable artifact — reports false, and like every tail step that degrades the report, never the land."
@@ -240,13 +240,13 @@ export function runLockedSuite(
240
240
  onLockProgress: lockHooks.onLockProgress,
241
241
  ...lockOptions,
242
242
  },
243
- ({ lockWaitMs }) =>
243
+ (lock) =>
244
244
  runSuiteImpl({
245
245
  cmd,
246
246
  args,
247
247
  cwd,
248
248
  timeoutMs,
249
- lockWaitMs,
249
+ ...lock,
250
250
  onTimings: (t) => {
251
251
  log(`[evidence-gate] ${formatSuiteTimings(t)}`);
252
252
  lockHooks.onTimings(t);
@@ -10,6 +10,7 @@ import { gitSpawn } from '../git-utils.js';
10
10
  import { resolveNavConfig } from '../orchestration/plan-navigation.js';
11
11
  import { withTimeout } from '../util/with-timeout.js';
12
12
  import { readAuditRulesSync } from './audit-rules-reader.js';
13
+ import { resolveSensitivePaths } from './sensitive-paths.js';
13
14
 
14
15
  const DEFAULT_GIT_TIMEOUT_MS = 30000;
15
16
 
@@ -47,25 +48,32 @@ export function resolveLensTier(lens) {
47
48
  }
48
49
 
49
50
  /**
50
- * Manifest `sensitivePaths` classes the change set touches (review depth).
51
+ * `sensitivePaths` classes the change set touches (review depth and plan
52
+ * routing): the shipped manifest merged with the consumer's own classes.
51
53
  *
52
54
  * @param {{
53
55
  * changedFiles?: string[],
54
56
  * injectedRules?: { sensitivePaths?: Record<string, { filePatterns?: string[] }> },
57
+ * injectedConfig?: object,
55
58
  * }} [params]
56
- * @returns {string[]} The matched class names, in manifest order.
59
+ * @returns {string[]} The matched class names, in effective-map order.
60
+ * @throws {Error} When the manifest or the config cannot be resolved.
57
61
  */
58
62
  export function selectSensitivePathClasses({
59
63
  changedFiles,
60
64
  injectedRules,
65
+ injectedConfig,
61
66
  } = {}) {
62
67
  const files = Array.isArray(changedFiles) ? changedFiles : [];
63
68
  if (files.length === 0) return [];
64
69
 
65
- const rules = injectedRules ?? readAuditRulesSync();
70
+ const effective = resolveSensitivePaths({
71
+ rules: injectedRules ?? readAuditRulesSync(),
72
+ config: injectedConfig ?? resolveConfig(),
73
+ });
66
74
  const matched = [];
67
- for (const [name, entry] of Object.entries(rules.sensitivePaths ?? {})) {
68
- if (matchesAnyFilePattern(entry?.filePatterns ?? [], files)) {
75
+ for (const [name, entry] of Object.entries(effective)) {
76
+ if (matchesAnyFilePattern(entry.filePatterns, files)) {
69
77
  matched.push(name);
70
78
  }
71
79
  }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * The effective `sensitivePaths` map: the shipped manifest's classes merged
3
+ * with the consumer's `delivery.codeReview.sensitivePaths`. The merge is
4
+ * additive only, so consumer config can make review stricter, never looser.
5
+ */
6
+
7
+ /**
8
+ * @typedef {{ description?: string, filePatterns: string[] }} SensitivePathClass
9
+ * @typedef {Record<string, { description?: string, filePatterns?: string[] }>} SensitivePathMap
10
+ */
11
+
12
+ /**
13
+ * @param {{
14
+ * rules?: { sensitivePaths?: SensitivePathMap }|null,
15
+ * config?: { delivery?: { codeReview?: { sensitivePaths?: SensitivePathMap } } }|null,
16
+ * }} [params]
17
+ * @returns {Record<string, SensitivePathClass>} Shipped classes in manifest
18
+ * order (consumer patterns appended, de-duplicated), then consumer-only
19
+ * classes in config order.
20
+ */
21
+ export function resolveSensitivePaths({ rules, config } = {}) {
22
+ const merged = {};
23
+ for (const [name, entry] of Object.entries(rules?.sensitivePaths ?? {})) {
24
+ merged[name] = { ...entry, filePatterns: [...(entry?.filePatterns ?? [])] };
25
+ }
26
+ const consumer = config?.delivery?.codeReview?.sensitivePaths ?? {};
27
+ for (const [name, entry] of Object.entries(consumer)) {
28
+ const patterns = entry?.filePatterns ?? [];
29
+ const shipped = merged[name];
30
+ if (shipped) {
31
+ shipped.filePatterns = [
32
+ ...new Set([...shipped.filePatterns, ...patterns]),
33
+ ];
34
+ } else {
35
+ merged[name] = { ...entry, filePatterns: [...new Set(patterns)] };
36
+ }
37
+ }
38
+ return merged;
39
+ }
@@ -99,7 +99,7 @@ export function defaultGateRunner(cmd, args, opts = {}) {
99
99
  // `skipIfSatisfied` re-probes after the wait: evidence another suite
100
100
  // deposited meanwhile is returned instead of spawning.
101
101
  return withFullSuiteLockAsync(gateLockOptions(opts), (lock) =>
102
- spawnGate(cmd, args, opts, lock),
102
+ spawnGate(cmd, args, { ...opts, env: { ...opts.env, ...lock.env } }, lock),
103
103
  );
104
104
  }
105
105
 
@@ -116,6 +116,37 @@ export const CODE_REVIEW_SCHEMA = {
116
116
  'Severity threshold for on-branch remediation in /mandrel-deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag.',
117
117
  default: DEFAULT_CODE_REVIEW.autoFixSeverity,
118
118
  },
119
+ sensitivePaths: {
120
+ type: 'object',
121
+ description:
122
+ "The project's own sensitive-path classes, merged additively over the shipped `audit-rules.json` `sensitivePaths`: a class named like a shipped one appends its patterns to it, a new name adds a class, and no shipped class or pattern can be removed or narrowed. A changed file matching any class derives a `high` change level, which drives both code-review depth (`deep`, never `light`) and plan-time routing. Patterns are picomatch globs matched with `dot: true`.",
123
+ propertyNames: { pattern: '^[a-z0-9][a-z0-9-]*$' },
124
+ additionalProperties: {
125
+ type: 'object',
126
+ required: ['filePatterns'],
127
+ properties: {
128
+ description: { type: 'string' },
129
+ filePatterns: {
130
+ type: 'array',
131
+ minItems: 1,
132
+ items: { type: 'string', minLength: 1 },
133
+ },
134
+ },
135
+ additionalProperties: false,
136
+ },
137
+ },
138
+ guidanceFile: {
139
+ type: 'string',
140
+ minLength: 1,
141
+ description:
142
+ "Project review guidance, a path relative to the project root. Unset, a root `REVIEW.md` is used when present; an absent file is a no-op. Its text is rendered into every LLM review provider's prompt after the framework's severity and anti-gaming rules, and over 8,000 characters is truncated with a degradation. Guidance may add failure classes and paths worth skipping but cannot lower a severity rule, excuse a `shortcut:`, or change the output shape.",
143
+ },
144
+ skipPaths: {
145
+ type: 'array',
146
+ items: { type: 'string', minLength: 1 },
147
+ description:
148
+ 'Picomatch globs (`dot: true`) whose findings are dropped after grounding and before severity is counted; the report states how many were dropped. A finding is dropped when its file, or every instance file, matches. Only config sets skip paths: guidance prose cannot silence a finding.',
149
+ },
119
150
  },
120
151
  additionalProperties: false,
121
152
  };
@@ -15,6 +15,7 @@ import path from 'node:path';
15
15
 
16
16
  import { getQuality } from './config/quality.js';
17
17
  import { mainCheckoutRoot } from './config/temp-paths.js';
18
+ import { resolveConfig } from './config-resolver.js';
18
19
  import { packageScriptArgv } from './detect-package-manager.js';
19
20
  import { isFirstInLine, waitInLine } from './full-suite-queue.js';
20
21
  import { acquireSweepLock } from './single-story-sweep/sweep-lock.js';
@@ -24,12 +25,15 @@ import {
24
25
  createAttempt,
25
26
  describeRefusal,
26
27
  FULL_SUITE_STALE_MS,
28
+ inheritedReservation,
29
+ reservationEnv,
27
30
  resolveAdmission,
28
31
  resolveSuiteCapacity,
32
+ SUITE_RESERVATION_ENV,
29
33
  } from './suite-admission.js';
30
34
  import { defaultSleep } from './util/sleep.js';
31
35
 
32
- export { ADMISSION_REFUSED_EXIT_CODE };
36
+ export { ADMISSION_REFUSED_EXIT_CODE, SUITE_RESERVATION_ENV };
33
37
 
34
38
  /** Environment escape hatch: set to `0`/`false`/`off`/`no` to disable. */
35
39
  export const FULL_SUITE_LOCK_ENV = 'MANDREL_FULL_SUITE_LOCK';
@@ -59,6 +63,7 @@ const LOCK_DEFAULTS = Object.freeze({
59
63
  pollMs: DEFAULT_POLL_MS,
60
64
  reportMs: DEFAULT_REPORT_MS,
61
65
  fsImpl: fs,
66
+ env: process.env,
62
67
  nowFn: Date.now,
63
68
  sleepFn: (ms) => defaultSleep(ms),
64
69
  acquireOnceFn: (opts) => acquireSweepLock(opts),
@@ -180,6 +185,7 @@ function consult(probe, applies) {
180
185
  * @param {{
181
186
  * cwd: string,
182
187
  * enabled?: boolean,
188
+ * env?: Record<string, string|undefined>,
183
189
  * log?: (m: string) => void,
184
190
  * waitMs?: number,
185
191
  * pollMs?: number,
@@ -196,22 +202,46 @@ function consult(probe, applies) {
196
202
  * onLockProgress?: (progress: import('./full-suite-queue.js').LockProgress) => void,
197
203
  * rerunCommand?: string,
198
204
  * }} opts A non-`undefined` `skipIfSatisfied` return stands in for the spawn.
199
- * @param {(timing: { lockWaitMs: number }) => Promise<T>} spawn
205
+ * `env` naming a live holder in this lock home spawns at once, inside it.
206
+ * @param {(lock: { lockWaitMs: number, env: Record<string, string> }) => Promise<T>} spawn
207
+ * `env` carries {@link SUITE_RESERVATION_ENV} for the child; merge it in.
200
208
  * @returns {Promise<T>}
201
209
  */
202
210
  export async function withFullSuiteLockAsync(options, spawn) {
203
211
  const opts = withDefaults(options);
204
212
  if (isRefused(opts)) return refuse(opts);
213
+ return admitAndSpawn(opts, spawn);
214
+ }
215
+
216
+ function admitAndSpawn(opts, spawn) {
217
+ const inherited = inheritedMarker(opts);
218
+ return inherited === null
219
+ ? lockAndSpawn(opts, spawn)
220
+ : spawnInside(opts, inherited, spawn);
221
+ }
222
+
223
+ async function lockAndSpawn(opts, spawn) {
205
224
  const begun = beginLock(opts);
206
225
  try {
207
226
  const wait = await awaitTurn(opts, begun);
208
227
  reportOutcome(opts.onLockOutcome, wait);
209
- return await spawnOrStandIn(opts, wait, spawn);
228
+ return await spawnOrStandIn(opts, wait, spawn, begun.attempt);
210
229
  } finally {
211
230
  begun.attempt?.release();
212
231
  }
213
232
  }
214
233
 
234
+ function inheritedMarker(opts) {
235
+ return inheritedReservation({ ...opts, lockHomeFn: () => lockHome(opts) });
236
+ }
237
+
238
+ function spawnInside(opts, marker, spawn) {
239
+ opts.log(
240
+ `${LOCK_TAG} ↪ already admitted under ${path.basename(marker)} — spawning inside it.`,
241
+ );
242
+ return spawn({ lockWaitMs: 0, env: reservationEnv(marker) });
243
+ }
244
+
215
245
  function isRefused({ enabled, workload }) {
216
246
  return enabled && workload?.kind === 'refused';
217
247
  }
@@ -253,7 +283,7 @@ function withDefaults(options) {
253
283
  return opts;
254
284
  }
255
285
 
256
- async function spawnOrStandIn(opts, wait, spawn) {
286
+ async function spawnOrStandIn(opts, wait, spawn, attempt) {
257
287
  const probe = consult(opts.skipIfSatisfied, wait.waited);
258
288
  if (probe.satisfied) {
259
289
  opts.log(
@@ -263,13 +293,16 @@ async function spawnOrStandIn(opts, wait, spawn) {
263
293
  }
264
294
  return wait.expired
265
295
  ? opts.onWaitExpired(wait.holder)
266
- : await timedSpawn(opts, wait, spawn);
296
+ : await timedSpawn(opts, wait, spawn, attempt);
267
297
  }
268
298
 
269
299
  /** Wait and execution reach progress as separate figures. */
270
- async function timedSpawn(opts, wait, spawn) {
300
+ async function timedSpawn(opts, wait, spawn, attempt) {
271
301
  const startedAt = opts.nowFn();
272
- const result = await spawn({ lockWaitMs: wait.waitedMs ?? 0 });
302
+ const result = await spawn({
303
+ lockWaitMs: wait.waitedMs ?? 0,
304
+ env: reservationEnv(attempt?.heldPath?.()),
305
+ });
273
306
  if (wait.waited) reportCompleted(opts, wait, opts.nowFn() - startedAt);
274
307
  return result;
275
308
  }
@@ -338,15 +371,55 @@ export function lockedCapture(
338
371
  env,
339
372
  coverageCaptureArgv(config, captureOpts),
340
373
  ),
374
+ env,
341
375
  ...lockOptions,
342
376
  cwd: captureOpts.cwd,
343
377
  log: captureOpts.log,
344
378
  skipIfSatisfied: freshnessProbe(captureOpts),
345
379
  },
346
- ({ lockWaitMs }) => runCaptureFn({ ...captureOpts, lockWaitMs }),
380
+ captureInLock(runCaptureFn, captureOpts),
347
381
  );
348
382
  }
349
383
 
384
+ /** The lock's marker joins the capture's own `env`, never replacing it. */
385
+ function captureInLock(runCaptureFn, captureOpts) {
386
+ return ({ lockWaitMs, env }) =>
387
+ runCaptureFn({
388
+ ...captureOpts,
389
+ env: { ...captureOpts.env, ...env },
390
+ lockWaitMs,
391
+ });
392
+ }
393
+
394
+ /**
395
+ * The consumer entry point: admit `argv` exactly as an in-framework caller
396
+ * would, or — when `env` already names a live holder — run inside it.
397
+ * Resolves to `spawn`'s result, 75 on an expired wait, or 78 on a refusal.
398
+ *
399
+ * @template T
400
+ * @param {{ argv: string[], cwd: string,
401
+ * env?: Record<string, string|undefined>, log?: (m: string) => void,
402
+ * config?: object, lockOptions?: object }} opts `lockOptions`: test seams.
403
+ * @param {(lock: { lockWaitMs: number, env: Record<string, string> }) => Promise<T>} spawn
404
+ * @returns {Promise<T|number>}
405
+ */
406
+ export function withSuiteAdmission(
407
+ { argv, cwd, env = process.env, log, config, lockOptions },
408
+ spawn,
409
+ ) {
410
+ const resolved = config ?? resolveConfig({ cwd });
411
+ return withFullSuiteLockAsync(
412
+ {
413
+ ...fullSuiteLockPolicy(resolved, env, argv),
414
+ ...lockOptions,
415
+ cwd,
416
+ env,
417
+ log,
418
+ },
419
+ spawn,
420
+ );
421
+ }
422
+
350
423
  /**
351
424
  * A fresh recheck means exit 0 without spawning.
352
425
  *