mandrel 2.43.0 → 2.44.0

package/.agents/scripts/lib/orchestration/plan-run-labels/reap.js

@@ -0,0 +1,327 @@
+/**
+ * plan-run-labels/reap.js — the cohort label's end of life (Story #5189).
+ *
+ * `plan-persist` mints one `plan-run::<id>` label per run so the Stories one
+ * plan authored stay filterable in the GitHub UI. That is load-bearing while
+ * any Story in the cohort is open, and inert the moment they are all closed —
+ * but nothing expressed the second half, so the vocabulary grew one label per
+ * persist forever. A consumer repository measured 235 `plan-run::` labels out
+ * of 313 total; past that a paged label listing stops seeing the labels that
+ * sort after the pile, and every list-then-create caller starts failing.
+ *
+ * This module is the **one decision engine** behind both surfaces that act on
+ * that end of life: the per-Story close tail (automatic, incremental) and
+ * `prune-plan-run-labels.js` (manual, whole-repository). Keeping the decision
+ * here rather than in either caller is what stops the two from disagreeing
+ * about when a label is spent.
+ *
+ * **The decision.** A cohort label is reapable only when it carries at least
+ * one issue and every issue carrying it is closed. The "at least one" clause
+ * is the subtle half: a label carrying *zero* issues is indistinguishable from
+ * one an in-flight persist has just minted before creating its Stories, and
+ * deleting it would break that run. So a zero-issue label is reported under an
+ * `unreferenced` reason and reaped only under an explicit opt-in — a default
+ * sweep is safe to run concurrently with a persist.
+ *
+ * **Never load-bearing.** Both surfaces treat a reap failure as a warning.
+ * Label hygiene is a chore; nothing downstream reads the cohort label as an
+ * input (see `PLAN_RUN_LABEL_PREFIX`'s own docblock), so a failed delete costs
+ * a stale label and nothing else.
+ *
+ * @module lib/orchestration/plan-run-labels/reap
+ * @see Story #5189
+ */
+
+import { PLAN_RUN_LABEL_PREFIX } from '../plan-persist/story-ops.js';
+
+/**
+ * Why a cohort label was — or was not — judged reapable. One reason per
+ * label, so a `--json` report is auditable without re-deriving anything.
+ *
+ * - `all-closed`   — carries issues, every one closed. Reapable.
+ * - `open-stories` — at least one issue still open. Not reapable, ever.
+ * - `unreferenced` — carries no issues at all. Reapable only under the
+ *   explicit opt-in, because an in-flight persist looks exactly like this.
+ */
+export const REAP_REASONS = Object.freeze({
+  ALL_CLOSED: 'all-closed',
+  OPEN_STORIES: 'open-stories',
+  UNREFERENCED: 'unreferenced',
+});
+
+/**
+ * Is `name` a plan-run cohort label?
+ *
+ * The prefix is imported from `plan-persist/story-ops.js` rather than
+ * re-declared: minting and reaping must not be able to drift onto two
+ * different strings, which is exactly the failure a copied literal invites.
+ *
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+function isPlanRunLabel(name) {
+  return typeof name === 'string' && name.startsWith(PLAN_RUN_LABEL_PREFIX);
+}
+
+/**
+ * Project an arbitrary label collection onto the sorted, de-duplicated set of
+ * cohort label names. Accepts either bare strings (a ticket's `labels[]`) or
+ * `{ name }` rows (the label listing port), so both callers hand this whatever
+ * their own read returned.
+ *
+ * @param {Array<string|{ name?: string }>} [names]
+ * @returns {string[]}
+ */
+function selectCohortLabels(names) {
+  const seen = new Set();
+  for (const raw of Array.isArray(names) ? names : []) {
+    const name = typeof raw === 'string' ? raw : raw?.name;
+    if (isPlanRunLabel(name)) seen.add(name);
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Decide one cohort label.
+ *
+ * Reads through `listIssuesByLabel({ state: 'all' })` — the paginating read
+ * port — so the verdict is never a function of how many issues fit on one API
+ * page. `state` is compared case-insensitively against `closed` and anything
+ * else counts as open: an unknown state must never be read as "safe to
+ * delete".
+ *
+ * @param {{ provider: object, label: string, includeUnreferenced?: boolean }} args
+ * @returns {Promise<{
+ *   label: string,
+ *   reapable: boolean,
+ *   reason: string,
+ *   issueCount: number,
+ *   openIssues: number[],
+ * }>}
+ */
+async function decideCohortLabel({
+  provider,
+  label,
+  includeUnreferenced = false,
+}) {
+  const result = await provider.listIssuesByLabel({
+    state: 'all',
+    labels: label,
+  });
+  const issues = Array.isArray(result) ? result : [];
+  const open = issues.filter(
+    (issue) => String(issue?.state ?? '').toLowerCase() !== 'closed',
+  );
+  if (issues.length === 0) {
+    return {
+      label,
+      reapable: includeUnreferenced === true,
+      reason: REAP_REASONS.UNREFERENCED,
+      issueCount: 0,
+      openIssues: [],
+    };
+  }
+  if (open.length > 0) {
+    return {
+      label,
+      reapable: false,
+      reason: REAP_REASONS.OPEN_STORIES,
+      issueCount: issues.length,
+      openIssues: open
+        .map((issue) => issue?.number)
+        .filter((n) => Number.isInteger(n)),
+    };
+  }
+  return {
+    label,
+    reapable: true,
+    reason: REAP_REASONS.ALL_CLOSED,
+    issueCount: issues.length,
+    openIssues: [],
+  };
+}
+
+/**
+ * Decide a set of cohort labels.
+ *
+ * Sequential on purpose. The whole-repository sweep can face hundreds of
+ * labels, and a fan-out over a shared REST budget buys wall-clock at the cost
+ * of the one property an operator auditing a pile actually needs: a
+ * deterministic, label-ordered report.
+ *
+ * @param {{
+ *   provider: object,
+ *   labels: Array<string|{ name?: string }>,
+ *   includeUnreferenced?: boolean,
+ * }} args
+ * @returns {Promise<Array<object>>} one decision per cohort label, name-sorted.
+ */
+async function evaluateCohortLabels({
+  provider,
+  labels,
+  includeUnreferenced = false,
+}) {
+  const decisions = [];
+  for (const label of selectCohortLabels(labels)) {
+    decisions.push(
+      await decideCohortLabel({ provider, label, includeUnreferenced }),
+    );
+  }
+  return decisions;
+}
+
+/**
+ * Decide, then (unless `check`) delete.
+ *
+ * A delete that throws is recorded in `failed[]` and warned about rather than
+ * propagated: one unreachable label must not abandon the rest of a sweep, and
+ * on the close path it must not touch the land. A delete the provider reports
+ * as a no-op (`deleted: false` — the label was already gone) is still a
+ * success; that is what makes a re-run idempotent.
+ *
+ * @param {{
+ *   provider: object,
+ *   labels: Array<string|{ name?: string }>,
+ *   includeUnreferenced?: boolean,
+ *   check?: boolean,
+ *   onWarn?: ((message: string) => void)|null,
+ * }} args
+ * @returns {Promise<{
+ *   check: boolean,
+ *   decisions: Array<object>,
+ *   reapable: string[],
+ *   deleted: Array<{ label: string, existed: boolean }>,
+ *   failed: Array<{ label: string, detail: string }>,
+ * }>}
+ */
+async function reapCohortLabels({
+  provider,
+  labels,
+  includeUnreferenced = false,
+  check = false,
+  onWarn = null,
+}) {
+  const decisions = await evaluateCohortLabels({
+    provider,
+    labels,
+    includeUnreferenced,
+  });
+  const reapable = decisions.filter((d) => d.reapable).map((d) => d.label);
+  const deleted = [];
+  const failed = [];
+  if (check !== true) {
+    for (const label of reapable) {
+      try {
+        const outcome = await provider.deleteLabel(label);
+        deleted.push({ label, existed: outcome?.deleted !== false });
+      } catch (err) {
+        const detail = String(err?.message ?? err);
+        failed.push({ label, detail });
+        onWarn?.(`could not delete cohort label "${label}": ${detail}`);
+      }
+    }
+  }
+  return { check: check === true, decisions, reapable, deleted, failed };
+}
+
+/**
+ * The automatic surface's entry point: reap the cohort labels carried by the
+ * Story that just closed.
+ *
+ * The Story's own label set comes from `getTicket` (labels are immutable for
+ * this purpose, so a cached snapshot is fine); every *state* judgment comes
+ * from the fresh `listIssuesByLabel` read inside {@link decideCohortLabel}, so
+ * a primed ticket cache cannot make a still-open sibling look closed.
+ *
+ * A Story whose own issue has not yet registered as closed — the merge webhook
+ * that fires `Closes #<id>` is not instantaneous — simply reports
+ * `open-stories` and is left alone. Deferring is the safe direction, and the
+ * manual sweep is the backstop that collects whatever a race leaves behind.
+ *
+ * @param {{
+ *   storyId: number,
+ *   provider: object,
+ *   includeUnreferenced?: boolean,
+ *   onWarn?: ((message: string) => void)|null,
+ * }} args
+ * @returns {Promise<object>} the {@link reapCohortLabels} envelope, plus
+ *   `evaluated` — how many cohort labels the Story carried.
+ */
+export async function reapPlanRunLabelsForStory({
+  storyId,
+  provider,
+  includeUnreferenced = false,
+  onWarn = null,
+}) {
+  const ticket = await provider.getTicket(storyId);
+  const labels = selectCohortLabels(ticket?.labels);
+  if (labels.length === 0) {
+    return {
+      evaluated: 0,
+      check: false,
+      decisions: [],
+      reapable: [],
+      deleted: [],
+      failed: [],
+    };
+  }
+  const outcome = await reapCohortLabels({
+    provider,
+    labels,
+    includeUnreferenced,
+    onWarn,
+  });
+  return { evaluated: labels.length, ...outcome };
+}
+
+/**
+ * The manual surface's entry point: sweep every cohort label in the repository.
+ *
+ * Reads the whole label vocabulary through the paginating listing port and
+ * projects it onto the cohort axis here, so the sweep is bounded by what the
+ * repository actually holds rather than by an API page size.
+ *
+ * @param {{
+ *   provider: object,
+ *   includeUnreferenced?: boolean,
+ *   check?: boolean,
+ *   onWarn?: ((message: string) => void)|null,
+ * }} args
+ * @returns {Promise<object>} the {@link reapCohortLabels} envelope, plus
+ *   `totalLabels` (whole vocabulary) and `evaluated` (the cohort slice).
+ */
+export async function sweepCohortLabels({
+  provider,
+  includeUnreferenced = false,
+  check = false,
+  onWarn = null,
+}) {
+  const all = await provider.listLabels();
+  const rows = Array.isArray(all) ? all : [];
+  const labels = selectCohortLabels(rows);
+  const outcome = await reapCohortLabels({
+    provider,
+    labels,
+    includeUnreferenced,
+    check,
+    onWarn,
+  });
+  return { totalLabels: rows.length, evaluated: labels.length, ...outcome };
+}
+
+/**
+ * Test-only surface. The five helpers below compose the two exported entry
+ * points (`reapPlanRunLabelsForStory`, `sweepCohortLabels`) and have no
+ * production consumer outside this module, so exporting each one individually
+ * would advertise five API surfaces nothing imports — and `dead-exports
+ * --production` correctly reports each as dead. They are still worth unit
+ * testing per arm, which is what this barrel is for; it follows the same
+ * `__testing` idiom `git-probes.js` and `source-classifier.js` use.
+ */
+export const __testing = {
+  isPlanRunLabel,
+  selectCohortLabels,
+  decideCohortLabel,
+  evaluateCohortLabels,
+  reapCohortLabels,
+};

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;