mandrel 2.53.0 → 2.55.0

package/.agents/scripts/lib/config/ci.js

@@ -12,6 +12,13 @@
  * `blockOnAdvisoryFailure: false` to restore the pre-#5096 behaviour verbatim,
  * or list a job name in `advisoryAllowlist` to exempt just that one.
  *
+ * Story #5266 added `rerunAdvisory`, **default `0`**. It is the number of
+ * times close may re-run a failed advisory workflow run before blocking on it.
+ * Zero is the deliberate default and not a placeholder: a rerun spends the
+ * consumer's CI minutes and mutates GitHub state, and close must never do
+ * either unasked. Raise it (or pass `--rerun-advisory <n>`) on a repository
+ * whose advisory scans time out transiently.
+ *
  * Retired (no production readers on v2 Story-only delivery): `earlyPr`
  * (Epic early-PR warmup) and `requireChecks` (AutomergePredicate escape hatch
  * whose listener was never landed).
@@ -21,6 +28,20 @@ export const CI_DELIVERY_DEFAULTS = Object.freeze({
   autoMerge: 'trust-ci',
   blockOnAdvisoryFailure: true,
   advisoryAllowlist: Object.freeze([]),
+  rerunAdvisory: 0,
+});
+
+/**
+ * Per-knob validators for the scalar `delivery.ci` settings. A value that
+ * fails its own test is not an instruction to guess — it degrades to the
+ * framework default beside it in {@link CI_DELIVERY_DEFAULTS}, which is why
+ * the two objects are keyed alike and read as a pair.
+ */
+const CI_KNOB_VALIDATORS = Object.freeze({
+  autoMerge: (value) => value === 'trust-ci' || value === 'strict',
+  blockOnAdvisoryFailure: (value) => typeof value === 'boolean',
+  // Story #5266 — a negative or non-integer allowance spends nothing.
+  rerunAdvisory: (value) => Number.isInteger(value) && value >= 0,
 });
 
 /**
@@ -31,19 +52,17 @@ export const CI_DELIVERY_DEFAULTS = Object.freeze({
  * defaults; only the scalar knobs carry framework defaults here.
  *
  * @param {object | null | undefined} config
- * @returns {{ autoMerge: 'trust-ci' | 'strict', watch: object | undefined }}
+ * @returns {{ autoMerge: 'trust-ci' | 'strict', blockOnAdvisoryFailure: boolean,
+ *   advisoryAllowlist: string[], rerunAdvisory: number, watch: object | undefined }}
  */
 export function getCiDelivery(config) {
   const ci = config?.delivery?.ci ?? config?.ci ?? config ?? {};
+  const knobs = {};
+  for (const [key, isValid] of Object.entries(CI_KNOB_VALIDATORS)) {
+    knobs[key] = isValid(ci[key]) ? ci[key] : CI_DELIVERY_DEFAULTS[key];
+  }
   return {
-    autoMerge:
-      ci.autoMerge === 'trust-ci' || ci.autoMerge === 'strict'
-        ? ci.autoMerge
-        : CI_DELIVERY_DEFAULTS.autoMerge,
-    blockOnAdvisoryFailure:
-      typeof ci.blockOnAdvisoryFailure === 'boolean'
-        ? ci.blockOnAdvisoryFailure
-        : CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    ...knobs,
     advisoryAllowlist: Array.isArray(ci.advisoryAllowlist)
       ? ci.advisoryAllowlist.filter(
           (entry) => typeof entry === 'string' && entry,

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -414,6 +414,13 @@ const CI_DELIVERY_SCHEMA = {
         'Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.',
       default: [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
     },
+    rerunAdvisory: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'Story #5266. How many times close may re-run a failed advisory workflow run before blocking on it, per close invocation. Default 0: close spends no CI minutes and issues no GitHub mutation on an advisory red unless asked. At n > 0 the failed run(s) are re-run within that allowance and the merge wait re-polls inside its existing budget, landing or blocking on the re-run verdict. Overridden per invocation by --rerun-advisory <n>.',
+      default: CI_DELIVERY_DEFAULTS.rerunAdvisory,
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config-settings-schema.js

@@ -16,6 +16,7 @@ import { SHELL_INJECTION_PATTERN_STRING } from './config-schema-shared.js';
 // resolved AGENTRC_SCHEMA is unchanged.
 import { DELIVERY_SCHEMA } from './config-settings-schema-delivery.js';
 import compiledAgentrcValidator from './generated/agentrc-validator.js';
+import { SKILL_ID_RE } from './skills/walk-skill-files.js';
 
 /**
  * Annotation contract (Story #5007). These schema literals are the SINGLE
@@ -529,6 +530,13 @@ const PLANNING_SCHEMA = {
             'Recommend a consolidation pass once this many entries have been written since the last one. Measured against the entry count the last pass stamped, so a stamp predating that field leaves growth unmeasured and only the age threshold applies. Default 25.',
           default: 25,
         },
+        indexByteCeiling: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            "Recommend a consolidation pass once the pool's `MEMORY.md` index exceeds this many bytes. Independent of the age and growth thresholds: the harness truncates the index it loads into each session at its own byte cap, so an oversized index is a loss already happening — every entry listed after the cut is invisible — rather than a hygiene forecast. Default 24576, the harness cap itself.",
+          default: 24576,
+        },
       },
       additionalProperties: false,
     },
@@ -681,7 +689,17 @@ const QA_SIGN_IN_SEAM_SCHEMA = {
     {
       type: 'object',
       properties: {
-        skill: { ...SAFE_STRING, minLength: 1 },
+        // The id is joined onto a skills root to reach a `SKILL.md`, so the
+        // shape is validated here rather than at the path join (Story #5285).
+        // `SKILL_ID_RE` is imported, never restated: one regex, two
+        // enforcement points — this schema and `resolveSkillFile`.
+        skill: {
+          ...SAFE_STRING,
+          minLength: 1,
+          pattern: SKILL_ID_RE.source,
+          description:
+            'Tier-relative skill id, e.g. `stack/qa/acme-sso`: lowercase segments of letters, digits, `.`, `_` or `-`, at least two of them, separated by `/`. A traversal (`../..`), an absolute path, a backslash or an uppercase segment is rejected here rather than normalized.',
+        },
       },
       required: ['skill'],
       additionalProperties: false,

package/.agents/scripts/lib/coverage-capture-fullscope.js

@@ -11,6 +11,7 @@ import path from 'node:path';
 import {
   anyChangedUnderTargets,
   describeFreshness,
+  stampCapturedTree,
 } from './coverage-capture.js';
 
 /**
@@ -77,10 +78,23 @@ export function runFullScopeCapture({
   logger.info(
     `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run test:coverage…`,
   );
+  // Story #5278 — the digest of the tree the suite is about to measure, taken
+  // BEFORE the spawn. That is the value the stamp claims; see
+  // `stampCapturedTree`.
+  const preDigest = computeContentDigestImpl(args.cwd, crap.targetDirs);
   const code = runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
+    // Story #5278 — consulted only if this capture had to queue behind
+    // another full suite on this host. Whoever we waited for may have just
+    // stamped this exact tree.
+    recheckFresh: () =>
+      isCoverageFreshImpl({
+        coveragePath: crap.coveragePath,
+        targetDirs: crap.targetDirs,
+        cwd: args.cwd,
+      }).fresh === true,
   });
   if (code !== 0) {
     logger.error(
@@ -93,16 +107,14 @@ export function runFullScopeCapture({
   // freshness checks are content-aware (mtime churn from branch switches no
   // longer invalidates). Best-effort — a missing stamp just means the next
   // check falls back to the mtime heuristic.
-  const digest = computeContentDigestImpl(args.cwd, crap.targetDirs);
-  if (
-    digest &&
-    writeCaptureStampImpl({
-      cwd: args.cwd,
-      coveragePath: crap.coveragePath,
-      digest,
-    })
-  ) {
-    logger.info('[coverage-capture] Wrote content-digest capture stamp.');
-  }
+  stampCapturedTree({
+    preDigest,
+    cwd: args.cwd,
+    targetDirs: crap.targetDirs,
+    coveragePath: crap.coveragePath,
+    computeContentDigestImpl,
+    writeCaptureStampImpl,
+    logger,
+  });
   return code;
 }

package/.agents/scripts/lib/coverage-capture-incremental.js

@@ -9,6 +9,7 @@
  * parameter (`.agents/rules/test-seams.md` rules 1-2, 4).
  */
 import path from 'node:path';
+import { stampCapturedTree } from './coverage-capture.js';
 
 /**
  * Run the skip-aware capture path when
@@ -97,10 +98,19 @@ export function tryIncrementalCapture({
   logger.info(
     `[coverage-capture] Incremental mode: ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}] — capturing…`,
   );
+  // Story #5278 — pre-spawn digest; see `stampCapturedTree`.
+  const preDigest = computeContentDigestImpl(args.cwd, crap.targetDirs);
   const code = runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
+    recheckFresh: () =>
+      isCoverageFreshImpl({
+        coveragePath: crap.coveragePath,
+        targetDirs: crap.targetDirs,
+        cwd: args.cwd,
+        requireScope: 'incremental',
+      }).fresh === true,
   });
   if (code !== 0) {
     logger.error(
@@ -109,21 +119,17 @@ export function tryIncrementalCapture({
     return code;
   }
 
-  const digest = computeContentDigestImpl(args.cwd, crap.targetDirs);
-  if (
-    digest &&
-    writeCaptureStampImpl({
-      cwd: args.cwd,
-      coveragePath: crap.coveragePath,
-      digest,
-      scope: 'incremental',
-      files: scopedFiles,
-      ref,
-    })
-  ) {
-    logger.info(
-      '[coverage-capture] Wrote content-digest capture stamp (incremental scope).',
-    );
-  }
+  stampCapturedTree({
+    preDigest,
+    cwd: args.cwd,
+    targetDirs: crap.targetDirs,
+    coveragePath: crap.coveragePath,
+    scope: 'incremental',
+    files: scopedFiles,
+    ref,
+    computeContentDigestImpl,
+    writeCaptureStampImpl,
+    logger,
+  });
   return code;
 }

package/.agents/scripts/lib/coverage-capture-usage.js

@@ -27,7 +27,7 @@ import { respondToHelp } from './cli-usage.js';
  */
 const COVERAGE_CAPTURE_USAGE = {
   invocation:
-    'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--ref <git-ref>] [--cwd <path>]',
+    'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--require-credited] [--ref <git-ref>] [--cwd <path>]',
   summary:
     'Ensure coverage/coverage-final.json is present and fresh before the CRAP gate fires, spawning `npm run test:coverage` only when it is stale. Writes a content-digest capture stamp that close-validation reads to skip a redundant re-run.',
   flags: [
@@ -35,6 +35,10 @@ const COVERAGE_CAPTURE_USAGE = {
       '--skip-when-no-crap-files',
       'Exit 0 without capturing when no changed file under the CRAP target dirs differs from --ref.',
     ],
+    [
+      '--require-credited',
+      'Refuse (exit 1) instead of spawning when no credited capture stamp covers this tree. Passed by the close gate when delivery.execution.requireCreditedCapture is set; a bare invocation always runs, so the deposit path stays open.',
+    ],
     ['--ref <git-ref>', 'Git ref the changed-file set is computed against.'],
     ['--cwd <path>', 'Repository root the capture runs in.'],
   ],

package/.agents/scripts/lib/coverage-capture.js

@@ -400,8 +400,12 @@ const CREDITING_INVOCATION =
  * @param {{
  *   requireCredited?: boolean,
  *   logger: { info: Function, warn: Function, error: Function },
- * }} opts `requireCredited` mirrors `delivery.execution.requireCreditedCapture`
- *   (default false → announce and run).
+ * }} opts `requireCredited` comes from the CLI's `--require-credited`
+ *   argument, which the close gate passes when
+ *   `delivery.execution.requireCreditedCapture` is set (default false →
+ *   announce and run). Story #5278: it is deliberately NOT read from config
+ *   here — that made the refusal cover the depositing invocation too, leaving
+ *   no way to earn the credit it demanded.
  * @returns {number | null} A non-zero exit code the caller MUST return
  *   without spawning the suite, or `null` to proceed with the capture.
  */
@@ -411,7 +415,7 @@ function announceUncreditedCapture({ requireCredited = false, logger }) {
     `the full suite is about to run. Deposit credit before the push with: ${CREDITING_INVOCATION}`;
   if (requireCredited) {
     logger.error(
-      `[coverage-capture] ✖ ${preamble} (delivery.execution.requireCreditedCapture is set, so this run is refused instead of paid for).`,
+      `[coverage-capture] ✖ ${preamble} (--require-credited was passed, so this run is refused instead of paid for).`,
     );
     return 1;
   }
@@ -445,6 +449,76 @@ export function creditedCapture(runCaptureFn, { requireCredited, logger }) {
   };
 }
 
+/**
+ * Write the capture stamp for a run that has just finished — but only when
+ * the tree it measured is still the tree on disk (Story #5278).
+ *
+ * The stamp is a claim about content: "coverage/coverage-final.json reflects
+ * sources digesting to X". Computing X *after* the suite finishes makes that
+ * claim false whenever anything moved while the suite ran — a sibling
+ * worktree's write, a rebase, an editor save minutes into a ten-minute run.
+ * The digest taken **before** the spawn is the one the run actually measured,
+ * so that is the value written, and a post-run digest that disagrees means
+ * the artifact describes a tree nobody has any more: no stamp is written at
+ * all, and the next reader captures rather than crediting a run against
+ * sources it never saw.
+ *
+ * A `null` on either digest is "unavailable", not "changed" — the same
+ * fail-open the pre-#5278 code had, since without a digest there is nothing
+ * to stamp.
+ *
+ * @param {{
+ *   preDigest: string|null,
+ *   cwd: string,
+ *   targetDirs: string[],
+ *   coveragePath: string,
+ *   scope?: 'full' | 'incremental',
+ *   files?: string[],
+ *   ref?: string,
+ *   computeContentDigestImpl: typeof computeContentDigest,
+ *   writeCaptureStampImpl: typeof writeCaptureStamp,
+ *   logger: { info: Function, warn: Function, error: Function },
+ * }} opts
+ * @returns {boolean} Whether a stamp was written.
+ */
+export function stampCapturedTree({
+  preDigest,
+  cwd,
+  targetDirs,
+  coveragePath,
+  scope,
+  files,
+  ref,
+  computeContentDigestImpl,
+  writeCaptureStampImpl,
+  logger,
+}) {
+  if (!preDigest) return false;
+  const postDigest = computeContentDigestImpl(cwd, targetDirs);
+  if (postDigest && postDigest !== preDigest) {
+    logger.warn(
+      '[coverage-capture] ⚠ the tree moved while the suite ran — the coverage ' +
+        'artifact measures sources that are no longer on disk, so no capture ' +
+        'stamp was written. The next capture will re-run against the current tree.',
+    );
+    return false;
+  }
+  const written = writeCaptureStampImpl({
+    cwd,
+    coveragePath,
+    digest: preDigest,
+    ...(scope === undefined ? {} : { scope }),
+    ...(files === undefined ? {} : { files }),
+    ...(ref === undefined ? {} : { ref }),
+  });
+  if (written) {
+    logger.info(
+      `[coverage-capture] Wrote content-digest capture stamp${scope ? ` (${scope} scope)` : ''}.`,
+    );
+  }
+  return written;
+}
+
 /**
  * Narrow `changedFiles` to the subset that lives under one of `targetDirs`.
  *

package/.agents/scripts/lib/findings/route-finding.js

@@ -160,12 +160,14 @@ export function semanticKeyFooter(keys) {
 /**
  * Extract semantic keys from an Issue body carrying the semantic-key footer.
  * The audit filers stamp the footer via {@link semanticKeyFooter}; the
- * confirmation path here and {@link carryProvenanceFooters} read it back.
+ * confirmation path here, {@link carryProvenanceFooters} and the audit dedup's
+ * local issue index read it back. Exported alongside its writer so an indexer
+ * cannot drift into a second parse of the same footer.
  *
  * @param {string} body
  * @returns {string[]}
  */
-function parseSemanticKeyFooter(body) {
+export function parseSemanticKeyFooter(body) {
   return parseAllFooterValues(
     body,
     /<!--\s*audit-semantic-keys:\s*([^>]*?)\s*-->/g,