mandrel 2.42.0 → 2.44.0

package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js

@@ -45,6 +45,28 @@
  * and that intent stands). It additionally reports a `degradations[]` array
  * naming **which** surface could not run and **why**, so the review outcome can
  * say "this gate did not run" instead of silently reading clean.
+ *
+ * ## The code surface never got the same treatment (Story #5193)
+ *
+ * Story #4839 gave the *markdown* surface a disk probe and left the code
+ * surface spawning `npx --no biome` and classifying the exit code. On npm 11.x
+ * that spawn exits **0 with empty output** when biome is absent, so
+ * `parseLintOutput` saw no failure, produced no degradation, and the surface
+ * contributed `errors: 0, warnings: 0` — a *silent false clean*, which is
+ * strictly worse than a degradation: a degraded surface announces itself, a
+ * falsely-clean one is trusted. Since nothing in the framework requires either
+ * runner, "absent" is the default state of a consumer checkout.
+ *
+ * Fix: runner resolution is a **precondition** for every surface, not an
+ * outcome inferred from an exit code. Both surfaces now resolve through
+ * {@link resolveRunner}, and an unresolved runner is never spawned.
+ *
+ * The same measurement invalidated the `NPX_UNRESOLVABLE` sentinel: current npm
+ * answers an unresolvable bin with `npm error code E404`, not `could not
+ * determine executable to run`, so every genuinely-unresolvable runner was
+ * being labelled `unparseable-output`. The sentinel now recognises both shapes.
+ * It still earns its keep after the disk probe: the probe only sees
+ * `node_modules/.bin`, so a runner resolvable some other way can still fail.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -54,8 +76,14 @@ import path from 'node:path';
 /** Paths these extensions land on the biome (code) runner. */
 const CODE_EXTENSIONS = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
 
-/** npx's message when the requested bin cannot be resolved. */
-const NPX_UNRESOLVABLE = /could not determine executable to run/i;
+/**
+ * npx's output when the requested bin cannot be resolved. Two shapes: the
+ * legacy message, and the `E404` current npm answers with instead (measured
+ * 2026-09-07 on npm 11.13.0). Matching the E404 *code* rather than any
+ * `npm error` line keeps a genuine runner error out of this classification.
+ */
+const NPX_UNRESOLVABLE =
+  /could not determine executable to run|npm (?:error|ERR!)\s+code\s+E404/i;
 
 /** Biome's exit-1 message when every supplied path is config-excluded. */
 const BIOME_EMPTY_SCOPE = /No files were processed in the specified paths/i;
@@ -74,6 +102,15 @@ const MARKDOWN_RUNNERS = Object.freeze([
   }),
 ]);
 
+/**
+ * Code runners in preference order. `@biomejs/biome` installs a bare `biome`
+ * bin, which is also the canonical name this surface reports itself under when
+ * nothing resolves.
+ */
+const CODE_RUNNERS = Object.freeze([
+  Object.freeze({ bin: 'biome', extraArgs: Object.freeze([]) }),
+]);
+
 /** Reason codes carried on a degradation record. */
 const DEGRADATION_REASONS = Object.freeze({
   RUNNER_NOT_INSTALLED: 'runner-not-installed',
@@ -103,24 +140,30 @@ function spawnLintRunner(bin, args, cwd) {
 }
 
 /**
- * Pure-ish: pick the first markdown runner whose bin is actually installed
- * under `<cwd>/node_modules/.bin`. Returns `null` when none is — an honest
- * "this surface has no runner" that the caller reports rather than silently
- * folding into a generic parse failure.
+ * Pure-ish: pick the first candidate whose bin is actually installed under
+ * `<cwd>/node_modules/.bin`. Returns `null` when none is — an honest "this
+ * surface has no runner" that the caller reports rather than silently folding
+ * into a generic parse failure.
  *
  * The disk probe (rather than "spawn and see") is what makes the failure
- * *nameable*: `npx --no <missing-bin>` yields only a generic npm error, which
- * is precisely how the defect hid for months.
+ * *nameable*, and — since Story #5193 — what makes it *visible at all* on the
+ * code surface: `npx --no <missing-bin>` answers with a generic npm error at
+ * best and an empty exit 0 at worst, which is precisely how both defects hid.
+ *
+ * Probing `node_modules/.bin` only is a deliberate bound: a globally-installed
+ * runner reads as absent here, which degrades the gate honestly rather than
+ * trusting a spawn nobody resolved.
  *
  * Not exported: it is reachable — and asserted — through {@link runScopedLint},
  * whose `existsFn` seam drives every resolution branch.
  *
+ * @param {ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>} candidates
  * @param {string} cwd
- * @param {(p: string) => boolean} [existsFn]  Injected for testing.
+ * @param {(p: string) => boolean} existsFn  Injected for testing.
  * @returns {{ bin: string, extraArgs: ReadonlyArray<string> }|null}
  */
-function resolveMarkdownRunner(cwd, existsFn = existsSync) {
-  for (const candidate of MARKDOWN_RUNNERS) {
+function resolveRunner(candidates, cwd, existsFn) {
+  for (const candidate of candidates) {
     const base = path.join(cwd, 'node_modules', '.bin', candidate.bin);
     if (existsFn(base)) return candidate;
     if (
@@ -133,6 +176,49 @@ function resolveMarkdownRunner(cwd, existsFn = existsSync) {
   return null;
 }
 
+/**
+ * Pure: the summary a surface reports when it has no runner to spawn. Counts
+ * are zero *and* `executionFailed` is true, so the row can never be read as a
+ * clean result — the invariant Story #5193 restored.
+ *
+ * @returns {ReturnType<typeof parseLintOutput>}
+ */
+function unresolvedRunnerSummary() {
+  return {
+    errors: 0,
+    warnings: 0,
+    parsed: false,
+    executionFailed: true,
+    emptyScope: false,
+    reason: DEGRADATION_REASONS.RUNNER_NOT_INSTALLED,
+  };
+}
+
+/**
+ * Resolve one surface's runner and, only if it resolved, spawn and classify it.
+ * Shared by both surfaces so neither can drift back into spawn-and-see.
+ *
+ * @param {{
+ *   label: string,
+ *   candidates: ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>,
+ *   buildArgs: (runner: { bin: string, extraArgs: ReadonlyArray<string> }) => string[],
+ *   cwd: string,
+ *   runnerFn: typeof spawnLintRunner,
+ *   existsFn: (p: string) => boolean,
+ * }} args
+ * @returns {{ surface: string, summary: ReturnType<typeof parseLintOutput> }}
+ */
+function runSurface({ label, candidates, buildArgs, cwd, runnerFn, existsFn }) {
+  const runner = resolveRunner(candidates, cwd, existsFn);
+  if (runner === null) {
+    return { surface: label, summary: unresolvedRunnerSummary() };
+  }
+  return {
+    surface: runner.bin,
+    summary: parseLintOutput(runnerFn(runner.bin, buildArgs(runner), cwd)),
+  };
+}
+
 /**
  * Pure: split changed paths into the file lists each lint runner consumes.
  *
@@ -267,33 +353,28 @@ export function runScopedLint(
 
   const surfaces = [];
   if (code.length > 0) {
-    surfaces.push({
-      surface: 'biome',
-      summary: parseLintOutput(runnerFn('biome', ['lint', ...code], cwd)),
-    });
+    surfaces.push(
+      runSurface({
+        label: 'biome',
+        candidates: CODE_RUNNERS,
+        buildArgs: (runner) => ['lint', ...code, ...runner.extraArgs],
+        cwd,
+        runnerFn,
+        existsFn,
+      }),
+    );
   }
   if (md.length > 0) {
-    const runner = resolveMarkdownRunner(cwd, existsFn);
-    if (runner === null) {
-      surfaces.push({
-        surface: 'markdownlint',
-        summary: {
-          errors: 0,
-          warnings: 0,
-          parsed: false,
-          executionFailed: true,
-          emptyScope: false,
-          reason: DEGRADATION_REASONS.RUNNER_NOT_INSTALLED,
-        },
-      });
-    } else {
-      surfaces.push({
-        surface: runner.bin,
-        summary: parseLintOutput(
-          runnerFn(runner.bin, [...md, ...runner.extraArgs], cwd),
-        ),
-      });
-    }
+    surfaces.push(
+      runSurface({
+        label: 'markdownlint',
+        candidates: MARKDOWN_RUNNERS,
+        buildArgs: (runner) => [...md, ...runner.extraArgs],
+        cwd,
+        runnerFn,
+        existsFn,
+      }),
+    );
   }
 
   return mergeSurfaceSummaries(surfaces);

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -44,6 +44,7 @@ import {
   executeFastForward as defaultExecuteFastForward,
   planFastForward as defaultPlanFastForward,
 } from '../../git-cleanup/phases/fast-forward.js';
+import { reapPlanRunLabelsForStory as defaultReapPlanRunLabelsForStory } from '../../plan-run-labels/reap.js';
 import { reassertStatusColumn as defaultReassertStatusColumn } from '../../reassert-status-column.js';
 import { releaseStoryLease as defaultReleaseStoryLease } from '../../single-story-lease-guard.js';
 import { captureStoryFollowUps as defaultCaptureStoryFollowUps } from '../../story-follow-ups.js';
@@ -290,6 +291,70 @@ async function stepLeaseRelease({
   };
 }
 
+/**
+ * The whole-repository sweep an operator runs when the automatic reap could
+ * not finish its job. Named in the warning itself so the next step is in the
+ * message rather than in a runbook nobody opens mid-incident.
+ */
+const REAP_SWEEP_REMEDY = 'node .agents/scripts/prune-plan-run-labels.js';
+
+/**
+ * Reap the cohort labels the closing Story carried (Story #5189).
+ *
+ * This seam is chosen deliberately. It is the only one that fires for both
+ * single- and multi-Story runs: the multi-Story run epilogue is keyed on a
+ * synthesized ad-hoc id, never sees the cohort label, and reports
+ * `applicable: false` at N=1 — which is the planning default, so wiring the
+ * reap there would leave the common case unreaped forever.
+ *
+ * Best-effort in the strongest sense the tail offers: the outcome is
+ * deliberately NOT reported in the returned `tail` envelope. A per-step
+ * boolean is the right shape for a step whose failure degrades the *report of
+ * the land* — a missed follow-up, an unresynced status column. Label
+ * vocabulary hygiene is not that: nothing downstream reads a cohort label as
+ * an input, so a failed reap costs one stale label. Surfacing it in the
+ * envelope would make a close whose label read flaked terminate differently
+ * from one where no label was reapable, for no difference an operator can act
+ * on. The failure is named in a warning instead, and the whole-repository
+ * sweep (`node .agents/scripts/prune-plan-run-labels.js`) collects whatever
+ * the automatic path misses.
+ *
+ * Never reaps a zero-issue label: that shape is indistinguishable from a label
+ * an in-flight persist has just minted, so the opt-in stays off here.
+ */
+async function stepPlanRunLabelReap({
+  storyId,
+  provider,
+  progress,
+  reapPlanRunLabelsForStoryFn,
+}) {
+  const warn = (message) =>
+    progress?.(
+      'POST-LAND',
+      `⚠️ plan-run label reap: ${message} — sweep the pile with ` +
+        `"${REAP_SWEEP_REMEDY}".`,
+    );
+  const outcome = await reapPlanRunLabelsForStoryFn({
+    storyId,
+    provider,
+    onWarn: warn,
+  });
+  const reaped = outcome?.deleted?.length ?? 0;
+  if (reaped > 0) {
+    progress?.(
+      'POST-LAND',
+      `🏷️  Reaped ${reaped} spent plan-run label(s): ` +
+        `${outcome.deleted.map((d) => d.label).join(', ')}.`,
+    );
+  }
+  return {
+    ok: (outcome?.failed?.length ?? 0) === 0,
+    detail: outcome?.failed?.length
+      ? outcome.failed.map((f) => f.label).join(', ')
+      : null,
+  };
+}
+
 /**
  * Run the whole post-land tail. Never throws.
  *
@@ -330,6 +395,7 @@ async function stepLeaseRelease({
  * @param {Function} [args.acquireLockWithWaitFn]   Test seam.
  * @param {Function} [args.purgeStoryTempArtifactsFn] Test seam.
  * @param {Function} [args.releaseStoryLeaseFn]     Test seam.
+ * @param {Function} [args.reapPlanRunLabelsForStoryFn] Test seam.
  * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, leaseRelease: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
@@ -350,6 +416,7 @@ export async function runPostLandTail({
   acquireLockWithWaitFn = defaultAcquireLockWithWait,
   purgeStoryTempArtifactsFn = defaultPurgeStoryTempArtifacts,
   releaseStoryLeaseFn = defaultReleaseStoryLease,
+  reapPlanRunLabelsForStoryFn = defaultReapPlanRunLabelsForStory,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -402,6 +469,20 @@ export async function runPostLandTail({
       }),
     { name: 'status-column resync', progress },
   );
+  // Story #5189 — the cohort label's end of life. Runs with the other
+  // GitHub-touching steps (outside the checkout lock) and contributes nothing
+  // to `tail`; see `stepPlanRunLabelReap` for why that omission is the point.
+  await step(
+    () =>
+      stepPlanRunLabelReap({
+        storyId,
+        provider,
+        progress,
+        reapPlanRunLabelsForStoryFn,
+      }),
+    { name: 'plan-run label reap', progress },
+  );
+
   // Local-checkout mutations: serialized behind a best-effort cross-process
   // lock (Story #4622). Acquire once, run both steps, release in `finally`.
   const lockCfg = config?.delivery?.postLandLock ?? {};

package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js

@@ -9,12 +9,17 @@
  * explicitly, and always state them (as `none` when healthy) so an absent line
  * can never be mistaken for a clean gate.
  *
- * A degraded gate is **reported, not blocking**: the canonical `npm run lint`
- * close-validation gate has already covered this diff before the review phase
- * runs, so failing the merge on a secondary read of an already-gated surface
- * would cost delivery without buying coverage. The rationale for that posture
- * lives with the channel itself in
+ * A degraded gate is **reported, not blocking**: this review is a secondary
+ * read, and the close does not gate the merge on it. The rationale for that
+ * posture lives with the channel itself in
  * [`review-providers/degraded-gates.js`](../../review-providers/degraded-gates.js).
+ *
+ * What this module must **not** do (Story #5193) is tell the operator that the
+ * canonical `npm run lint` close gate covered the surface instead. A stub
+ * `lint` script is a supported consumer shape, so that claim is unverifiable
+ * from here — and asserting it talks the operator out of the exact concern the
+ * degradation was raised to surface. State the posture; never vouch for
+ * coverage this module cannot see.
  */
 
 import { summarizeDegradations } from '../../review-providers/degraded-gates.js';
@@ -58,8 +63,8 @@ export function formatReviewOutcomeLines({
   if (summarizeDegradations(degradations) !== 'none') {
     lines.push(
       '⚠️ Review ran DEGRADED — the surface(s) above were not reviewed. The close ' +
-        'is not blocked (the canonical `npm run lint` close gate already covered ' +
-        'this diff), but this review does not vouch for them.',
+        'is not blocked — a secondary review does not gate the merge — but ' +
+        'nothing here vouches for those surfaces.',
     );
   }
   return lines;

package/.agents/scripts/providers/github/labels.js

@@ -17,6 +17,7 @@
  */
 
 import { withTransientRetry } from './errors.js';
+import { paginateRest } from './request-helpers.js';
 
 /**
  * Detect the "label already exists" signal across the surfaces `gh label
@@ -60,6 +61,28 @@ export function isLabelAlreadyExistsError(err) {
   return false;
 }
 
+/**
+ * Detect the "label does not exist" signal on the delete path. `gh api` exits
+ * non-zero on a 404 with `gh: Not Found (HTTP 404)` on stderr; the REST body
+ * carries `"message": "Not Found"`. Both are matched, and the numeric status
+ * is matched on its own so a transport that surfaces only `err.status` still
+ * classifies.
+ *
+ * Deliberately narrow: only a 404 counts. A 403 (scope) or a 422 must stay
+ * loud, because reading either as "already gone" would let a sweep report
+ * labels as reaped that are all still there.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isLabelNotFoundError(err) {
+  if (!err) return false;
+  if (err.status === 404 || err.statusCode === 404) return true;
+  return /\bHTTP\s+404\b|\bnot found\b/i.test(
+    `${err.message ?? ''} ${err.stderr ?? ''}`,
+  );
+}
+
 export class LabelGateway {
   /**
    * @param {{ gh: object, owner: string, repo: string }} deps
@@ -162,6 +185,71 @@ export class LabelGateway {
     return missing;
   }
 
+  /**
+   * List the repository's whole label vocabulary, paginated.
+   *
+   * Deliberately NOT modelled on `_reconcileLabelsPresence`'s
+   * `gh label list --limit 500`. That hard cap is fine for its own job —
+   * "are these 20 bootstrap labels present?" — and fatal for this one: a
+   * caller deciding which labels to delete from a truncated view would skip
+   * exactly the labels that sort after an accumulated pile, which is the
+   * failure Story #5189 exists to stop reproducing. `paginateRest` walks
+   * pages until a short one lands and throws (loudly) rather than truncating
+   * if the repository somehow exceeds its ceiling.
+   *
+   * Rows are projected to the fields a caller can rely on; a row without a
+   * usable `name` is dropped rather than passed on as a deletable target.
+   *
+   * @returns {Promise<Array<{ name: string, color: string|null, description: string|null }>>}
+   * @field-manifest /repos/{owner}/{repo}/labels: name, color, description
+   */
+  async listLabels() {
+    const endpoint = `/repos/${this.owner}/${this.repo}/labels`;
+    const rows = await paginateRest(this._gh, endpoint, {
+      label: `listLabels ${this.owner}/${this.repo}`,
+    });
+    return (Array.isArray(rows) ? rows : [])
+      .filter((row) => typeof row?.name === 'string')
+      .map((row) => ({
+        name: row.name,
+        color: row.color ?? null,
+        description: row.description ?? null,
+      }));
+  }
+
+  /**
+   * Delete one label by name.
+   *
+   * Goes through the REST surface (`DELETE /repos/{owner}/{repo}/labels/{name}`)
+   * rather than `gh label delete`, so the "already gone" signal arrives as a
+   * structured 404 on the same facade every other read here uses instead of
+   * as CLI prose — and so this gateway needs no new verb on the `gh` facade.
+   *
+   * A missing label resolves as a successful no-op. That is not leniency: the
+   * sweep this port exists for is expected to run repeatedly and concurrently
+   * with the close-path reap, so "someone else already deleted it" is the
+   * normal case, not an error.
+   *
+   * @param {string} name
+   * @returns {Promise<{ deleted: boolean, reason: string|null }>}
+   */
+  async deleteLabel(name) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+      throw new Error('deleteLabel: a non-empty label name is required');
+    }
+    const endpoint = `/repos/${this.owner}/${this.repo}/labels/${encodeURIComponent(name)}`;
+    try {
+      await withTransientRetry(() =>
+        this._gh.api({ method: 'DELETE', endpoint }),
+      );
+      return { deleted: true, reason: null };
+    } catch (err) {
+      if (isLabelNotFoundError(err))
+        return { deleted: false, reason: 'not-found' };
+      throw err;
+    }
+  }
+
   _normalizeLabelListResult(result) {
     if (Array.isArray(result)) return result;
     if (result && typeof result.stdout === 'string') {

package/.agents/scripts/providers/github.js

@@ -133,6 +133,8 @@ const DELEGATIONS = [
   ['getBranchProtection', 'branchProtection.getBranchProtection'],
   ['setBranchProtection', 'branchProtection.setBranchProtection'],
   ['ensureLabels', 'labels.ensureLabels'],
+  ['listLabels', 'labels.listLabels'],
+  ['deleteLabel', 'labels.deleteLabel'],
   ['_reconcileLabelsPresence', 'labels._reconcileLabelsPresence'],
   ['getMergeMethods', 'mergeMethods.getMergeMethods'],
   ['setMergeMethods', 'mergeMethods.setMergeMethods'],