mandrel 2.24.0 → 2.26.0

package/.agents/scripts/lib/cli-args.js

@@ -62,13 +62,71 @@ function parsePositiveInt(value) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+/** The only two merge-watch postures `--merge-watch-mode` accepts. */
+const MERGE_WATCH_MODES = ['sync', 'async'];
+
+/**
+ * Parse `--merge-watch-mode` (Story #4949), the per-invocation override of
+ * `delivery.mergeWatch.mode`. Absence is preserved as `undefined` so the
+ * caller can distinguish "not supplied" (fall back to config) from an explicit
+ * posture — the same contract {@link parsePositiveInt} gives
+ * `--max-wait-seconds`.
+ *
+ * Unlike that sibling, an unrecognized value **throws** rather than degrading
+ * to absent. A `--max-wait-seconds` typo falls back to a sane bound; a
+ * `--merge-watch-mode` typo would fall back to `sync` and silently return a
+ * multi-Story run to a serialized foreground wait per close, with the wall
+ * clock as the only evidence. Parsing runs before the first close phase, so
+ * failing here costs no mutation.
+ *
+ * @param {unknown} value
+ * @returns {'sync'|'async'|undefined}
+ */
+export function parseMergeWatchMode(value) {
+  if (value == null) return undefined;
+  const mode = String(value).trim().toLowerCase();
+  if (MERGE_WATCH_MODES.includes(mode)) return mode;
+  throw new Error(
+    `--merge-watch-mode must be one of ${MERGE_WATCH_MODES.join('|')} (got "${value}")`,
+  );
+}
+
+/**
+ * {@link parseMergeWatchMode} degraded to the "absent" value instead of
+ * throwing — how the tolerant parse below treats a flag that failed
+ * validation. Reporting `undefined` is safe there and only there, because a
+ * tolerant parse never drives a pipeline: its caller surfaces the rejection
+ * as the run's failure and runs no phase at all.
+ *
+ * @param {unknown} value
+ * @returns {'sync'|'async'|undefined}
+ */
+function tolerantMergeWatchMode(value) {
+  try {
+    return parseMergeWatchMode(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Standardized CLI argument parser for sprint scripts.
  * Supports options like --epic, --story, --dry-run, --skip-dashboard.
+ *
+ * Throws when a *validating* parser rejects a flag value (currently only
+ * `--merge-watch-mode`). Callers that must not throw — an error handler
+ * needing `storyId` to report an envelope — use {@link parseSprintArgsTolerant}
+ * rather than calling this a second time inside their own catch.
+ *
  * @param {string[]} args Array of arguments (defaults to process.argv)
+ * @param {{ tolerant?: boolean }} [options] `tolerant` degrades a rejected
+ *   flag to its absent value instead of throwing. For reporting only.
  * @returns {object} Parsed and typed argument values
  */
-export function parseSprintArgs(args = process.argv) {
+export function parseSprintArgs(
+  args = process.argv,
+  { tolerant = false } = {},
+) {
   const { values, positionals } = parseArgs({
     args: args.slice(2),
     options: {
@@ -85,6 +143,10 @@ export function parseSprintArgs(args = process.argv) {
       // Story #4543 — per-run override of `delivery.mergeWatch.maxWaitSeconds`
       // (the merge wait's per-invocation bound). Absent means "use the config".
       'max-wait-seconds': { type: 'string' },
+      // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
+      // Absent means "use the config"; see `parseMergeWatchMode` for why an
+      // unrecognized value fails closed instead of degrading to absent.
+      'merge-watch-mode': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -115,6 +177,12 @@ export function parseSprintArgs(args = process.argv) {
     // headless caller with no host tool-invocation ceiling, so it lands in
     // one block instead of returning `pending` at the default 300s.
     maxWaitSeconds: parsePositiveInt(values['max-wait-seconds']),
+    // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
+    // `undefined` when the flag is absent, which is what lets the merge wait
+    // fall back to the config; anything unrecognized throws here.
+    mergeWatchMode: tolerant
+      ? tolerantMergeWatchMode(values['merge-watch-mode'])
+      : parseMergeWatchMode(values['merge-watch-mode']),
     executor: values.executor ?? null,
     // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:
@@ -137,6 +205,52 @@ export function parseSprintArgs(args = process.argv) {
   return parsed;
 }
 
+/**
+ * Last-resort tolerant parse: the fields, or an empty bag if even the
+ * tolerant pass cannot produce one.
+ *
+ * @param {string[]} args
+ * @returns {object}
+ */
+function parseSprintArgsOrEmpty(args) {
+  try {
+    return parseSprintArgs(args, { tolerant: true });
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse argv **without ever throwing**, returning the fields alongside the
+ * rejection rather than in place of it.
+ *
+ * `parseSprintArgs` gained its first *validating* parser in
+ * {@link parseMergeWatchMode} (Story #4949), which made a latent shape in the
+ * CLI entries fatal: their catch blocks called
+ * `failedTerminalFor(err, parseSprintArgs())` — re-invoking the very parser
+ * that had just thrown. The second throw escaped the catch, so an
+ * unparseable argv produced a bare stack trace with **no terminal envelope
+ * and no friction signal**, on the two surfaces whose whole contract is that
+ * they always emit one. An error handler must not depend on an operation
+ * already known to fail.
+ *
+ * So the entries parse **once**, up front, through this wrapper: `args`
+ * carries the `storyId` and skip flags the envelope is built from, and
+ * `error` is the failure to report. The tolerant re-parse degrades **only**
+ * the flag that failed validation; every other field parses normally. Use
+ * the result to *report*, never to run a pipeline.
+ *
+ * @param {string[]} [args] Array of arguments (defaults to `process.argv`)
+ * @returns {{ args: object, error: Error|null }}
+ */
+export function parseSprintArgsTolerant(args = process.argv) {
+  try {
+    return { args: parseSprintArgs(args), error: null };
+  } catch (error) {
+    return { args: parseSprintArgsOrEmpty(args), error };
+  }
+}
+
 const SUPPORTED_FLAG_TYPES = new Set([
   'boolean',
   'ticket',

package/.agents/scripts/lib/close-validation/runner.js

@@ -315,17 +315,79 @@ export async function runCloseValidation({
   }
 
   // ── Phase 2: serial gates in declared order ─────────────────────────
+  await runSerialGates(serial, {
+    spawnCwd,
+    log,
+    failed,
+    skipped,
+    evidenceActive,
+    evidenceClock,
+    evidenceVerdict,
+    recordIfActive,
+    dispatchGate,
+  });
+
+  // ── Phase 3: advisory projections ───────────────────────────────────
+  // Story #4776 — the projection layer's live call site. Deliberately
+  // outside the `ok` computation: a projected breach informs, it never
+  // fails a close.
+  if (failed.length === 0) {
+    await runAdvisoryProjections({
+      runProjections,
+      cwd: spawnCwd,
+      baseBranch,
+      storyBranch,
+      config,
+      log,
+    });
+  }
+
+  return { ok: failed.length === 0, failed, skipped };
+}
+
+/**
+ * Phase 2 helper — run the serial gates in declared order, stopping at the
+ * first failure. Extracted from `runCloseValidation` (Story #4926); the
+ * evidence bookkeeping stays bit-identical to the parallel pass because both
+ * call the same injected `evidenceVerdict` / `recordIfActive` closures.
+ *
+ * Mutates the caller's `failed` / `skipped` accumulators — the same arrays
+ * Phase 1 already wrote into, so the returned verdict stays one list.
+ *
+ * @param {Array<object>} serial
+ * @param {object} deps
+ * @returns {Promise<void>}
+ */
+async function runSerialGates(
+  serial,
+  {
+    spawnCwd,
+    log,
+    failed,
+    skipped,
+    evidenceActive,
+    evidenceClock,
+    evidenceVerdict,
+    recordIfActive,
+    dispatchGate,
+  },
+) {
+  const failGate = (gate, status, message) => {
+    failed.push({ gate, status, cwd: spawnCwd });
+    log(message);
+    if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+  };
   for (const gate of serial) {
     let execution;
     try {
       execution = applyChangedFileScope({ gate, spawnCwd, log });
     } catch (err) {
-      failed.push({ gate, status: 1, cwd: spawnCwd });
-      log(
+      failGate(
+        gate,
+        1,
         `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
       );
-      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
-      break;
+      return;
     }
     if (execution.skip) {
       skipped.push({ gate, reason: 'no-changed-files' });
@@ -349,12 +411,12 @@ export async function runCloseValidation({
       tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
     });
     if (result.status !== 0) {
-      failed.push({ gate, status: result.status, cwd: spawnCwd });
-      log(
+      failGate(
+        gate,
+        result.status,
         `[close-validation] ✖ ${gate.name} failed (exit ${result.status}) in ${spawnCwd}`,
       );
-      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
-      break;
+      return;
     }
     log(`[close-validation] ✓ ${gate.name}`);
     recordIfActive(
@@ -363,23 +425,6 @@ export async function runCloseValidation({
       evidenceActive ? evidenceClock() - startedAt : 0,
     );
   }
-
-  // ── Phase 3: advisory projections ───────────────────────────────────
-  // Story #4776 — the projection layer's live call site. Deliberately
-  // outside the `ok` computation: a projected breach informs, it never
-  // fails a close.
-  if (failed.length === 0) {
-    await runAdvisoryProjections({
-      runProjections,
-      cwd: spawnCwd,
-      baseBranch,
-      storyBranch,
-      config,
-      log,
-    });
-  }
-
-  return { ok: failed.length === 0, failed, skipped };
 }
 
 /**

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

@@ -214,12 +214,17 @@ const ROUTING_SCHEMA = {
 // the merge/CI watch poll loop; `autoMerge` selects the merge posture.
 // Retired: `earlyPr` (Epic early-PR warmup) and `requireChecks` (no
 // AutomergePredicate reader on v2).
+// Story #4890 added `attachWindowMs`: how long the watch keeps re-resolving an
+// EMPTY required-check set before it stops waiting for one. This block is
+// `additionalProperties: false`, so the knob is inert unless it lands here AND
+// in the `.agents/schemas/agentrc.schema.json` mirror.
 const CI_WATCH_SCHEMA = {
   type: 'object',
   properties: {
     pollIntervalMs: { type: 'integer', minimum: 1 },
     maxPolls: { type: 'integer', minimum: 1 },
     maxResumes: { type: 'integer', minimum: 0 },
+    attachWindowMs: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/crap-engine.js

@@ -1,5 +1,24 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
+import { deriveMethodIdentities } from './crap-method-identity.js';
+
+/**
+ * The two line coordinate systems a CRAP row's `startLine` can be expressed
+ * in (Story #4866).
+ *
+ * `original` — the coordinates of the file a reader can open, and the ones
+ * istanbul's `fnMap` is keyed against. A JavaScript source is already in this
+ * system; a TS/TSX source reaches it only through a successful sourcemap
+ * lookup.
+ *
+ * `transpiled` — escomplex's own coordinates over the emitted JavaScript,
+ * kept only when the sourcemap has no entry originating on the method's
+ * generated line. Such a row is NOT an original-source coordinate and must
+ * never be presented as one: it cannot be joined to coverage, and it cannot
+ * be compared against a baseline row carrying the other provenance.
+ */
+export const COORDINATE_ORIGINAL = 'original';
+export const COORDINATE_TRANSPILED = 'transpiled';
 
 /**
  * Derive the raw per-method CRAP rows from an escomplex report.
@@ -9,41 +28,86 @@ import { coverageForMethodInEntry } from './coverage-utils.js';
  * method's line is remapped or its coverage joined — the parity the
  * combined-parity suite asserts.
  *
- * **Coordinates (Story #4775).** `mapLine` translates escomplex's
- * `lineStart` — which is in *transpiled* coordinates for a TS/TSX source —
- * into the *original source* coordinates istanbul's `fnMap` uses. Without it
- * the join compares two different coordinate systems and either misses or,
- * worse, collides with an unrelated function. A `null` mapper means the two
- * coordinate systems already coincide (plain JavaScript), and a line the map
- * cannot resolve falls back to the un-remapped value rather than dropping the
- * method outright. The remapped line is also what the row reports, so a
- * persisted row points at a line the reader can actually open.
+ * **Coordinates (Story #4775, corrected by Story #4866).** `mapLine`
+ * translates escomplex's `lineStart` — which is in *transpiled* coordinates
+ * for a TS/TSX source — into the *original source* coordinates istanbul's
+ * `fnMap` uses. A `null` mapper means the two coordinate systems already
+ * coincide (plain JavaScript).
+ *
+ * #4775 let an unresolvable line fall back to the un-remapped value, which
+ * made one scan emit rows in two coordinate systems with nothing on the row
+ * saying which. Each row now records its own `coordinateSystem`, and an
+ * un-remapped row joins no coverage at all: joining a transpiled line against
+ * an original-source `fnMap` does not merely miss, it can land inside an
+ * unrelated function's range and mis-attribute that function's coverage. An
+ * honest `coverage: null` lets the scanner's `requireCoverage` policy decide,
+ * exactly as it does for a genuinely uninstrumented method.
  *
  * @param {object|null} report An `escomplex.analyzeModule` report.
  * @param {object|null} coverageForFile Istanbul coverage entry for this file.
  * @param {((line: number) => number|null)|null} [mapLine]
  * @returns {Array<{
  *   method: string,
+ *   anonymous: boolean,
  *   startLine: number,
  *   cyclomatic: number,
  *   coverage: number|null,
  *   crap: number|null,
+ *   coordinateSystem: 'original'|'transpiled',
  * }>}
  */
+/**
+ * Resolve one method's line into a coordinate and the provenance of that
+ * coordinate — the single place the rule lives.
+ *
+ * No mapper means the source was never transpiled, so its line already IS an
+ * original-source coordinate. A mapper that resolves yields one. A mapper
+ * that does not leaves the transpiled line, said so.
+ *
+ * @param {number} rawStartLine escomplex's `lineStart`.
+ * @param {((line: number) => number|null)|null} mapLine
+ * @returns {{startLine: number, coordinateSystem: 'original'|'transpiled'}}
+ */
+function resolveCoordinate(rawStartLine, mapLine) {
+  if (typeof mapLine !== 'function') {
+    return { startLine: rawStartLine, coordinateSystem: COORDINATE_ORIGINAL };
+  }
+  const mapped = mapLine(rawStartLine);
+  return typeof mapped === 'number'
+    ? { startLine: mapped, coordinateSystem: COORDINATE_ORIGINAL }
+    : { startLine: rawStartLine, coordinateSystem: COORDINATE_TRANSPILED };
+}
+
 export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
   const methods = report?.methods ?? [];
+  // Identities are derived over the WHOLE method list, before any row is
+  // skipped, and read back by index (Story #4969). Deriving them from the
+  // surviving rows instead would let an unscorable method's absence shift its
+  // siblings' ordinals — reintroducing, through the back door, exactly the
+  // position dependence this replaces.
+  const identities = deriveMethodIdentities(methods);
   const rows = [];
-  for (const m of methods) {
+  for (const [i, m] of methods.entries()) {
     const rawStartLine = m?.lineStart;
     if (typeof rawStartLine !== 'number') continue;
-    const mapped = typeof mapLine === 'function' ? mapLine(rawStartLine) : null;
-    const startLine = typeof mapped === 'number' ? mapped : rawStartLine;
+    const { startLine, coordinateSystem } = resolveCoordinate(
+      rawStartLine,
+      mapLine,
+    );
     const cyclomatic = m?.cyclomatic ?? 0;
-    const coverage = coverageForFile
-      ? coverageForMethodInEntry(coverageForFile, startLine)
-      : null;
+    const coverage =
+      coverageForFile && coordinateSystem === COORDINATE_ORIGINAL
+        ? coverageForMethodInEntry(coverageForFile, startLine)
+        : null;
     const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
-    rows.push({ method: m.name, startLine, cyclomatic, coverage, crap });
+    rows.push({
+      ...identities[i],
+      startLine,
+      cyclomatic,
+      coverage,
+      crap,
+      coordinateSystem,
+    });
   }
   return rows;
 }
@@ -63,13 +127,32 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
  *     dropped, which made it a no-op for baseline population — the caller
  *     asked for "score it anyway" and got silence.
  *
- * `resolvedMethods` / `totalMethods` count the *join*, not the fill: a
- * method scored 0% because its coverage was unresolved counts as
- * unresolved. That is what makes them usable as a health signal for the
- * updater's fail-closed resolution-rate floor.
+ * **Absent coverage is not zero coverage (Story #4871).** The 0%-covered
+ * inference above is only defensible when a coverage **artifact** exists and
+ * simply reports nothing for this method — "the tests ran and never reached
+ * it" is a measurement. When no artifact was produced at all — a freshly
+ * initialized story worktree, whose `coverage/` directory does not exist —
+ * nothing was measured, and filling the gap with 0% manufactures a maximal
+ * CRAP out of an absent observation, failing the first commit on files the
+ * change never touched. `coverageAvailable: false` therefore makes such a
+ * method **unscorable** under either policy: skipped and counted, never
+ * filled. It is deliberately keyed on the artifact, not the per-file entry,
+ * so `requireCoverage: false` keeps meaning "score untested code" whenever a
+ * real coverage run stands behind the verdict.
+ *
+ * **Unjoinable is not untested (Story #4901).** Both policies above are about
+ * a method whose coverage is *absent*; neither is about one whose coverage
+ * could not be **joined**. A transpiled `startLine` is the latter — not in
+ * the coordinate space the `fnMap` or the baseline is keyed against — so 0%
+ * is not a measurement but a number invented for it, and `crapFormula(c, 0)`
+ * is the maximal `c² + c`. Excluded under **either** policy, and counted.
+ *
+ * `resolvedMethods` / `totalMethods` count the *join*, not the fill, which is
+ * what makes them a health signal for the updater's fail-closed
+ * resolution-rate floor — so the exclusion is applied *after* both counters.
  *
  * @param {Array<object>} rawRows Rows from `methodRowsFromReport`.
- * @param {{requireCoverage?: boolean}} [opts]
+ * @param {{requireCoverage?: boolean, coverageAvailable?: boolean}} [opts]
  * @returns {{
  *   rows: Array<object>,
  *   skippedMethodsNoCoverage: number,
@@ -77,7 +160,10 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
  *   totalMethods: number,
  * }}
  */
-export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
+export function finalizeMethodRows(
+  rawRows,
+  { requireCoverage = true, coverageAvailable = true } = {},
+) {
   const rows = [];
   let skippedMethodsNoCoverage = 0;
   let resolvedMethods = 0;
@@ -86,18 +172,26 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
     totalMethods += 1;
     const unresolved = mr.crap === null || mr.coverage === null;
     if (!unresolved) resolvedMethods += 1;
-    if (unresolved && requireCoverage) {
+    // Unjoinable is not untested (Story #4901) — see the block comment above.
+    if (
+      mr.coordinateSystem === COORDINATE_TRANSPILED ||
+      (unresolved && (requireCoverage || !coverageAvailable))
+    ) {
       skippedMethodsNoCoverage += 1;
       continue;
     }
     const coverage = unresolved ? 0 : mr.coverage;
     const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
+    // Everything the scan decided is carried forward; this step overrides only
+    // what its own policy resolves. Spreading rather than re-listing each field
+    // is why the row's identity marker (Story #4969) and its provenance
+    // (Story #4866) survive the step without a line each to remember them —
+    // a hand-rebuilt row is how a marker silently stops reaching the baseline.
     rows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
+      ...mr,
       coverage,
       crap,
+      coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
     });
   }
   return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
@@ -111,7 +205,8 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
  * Kernel contract:
  *   - Pure (no I/O, no AST parse beyond the one delegated to escomplex via
  *     `analyzeModule`).
- *   - Methods whose coverage cannot be resolved from `coverageForFile`
+ *   - Methods whose coverage cannot be resolved from `coverageForFile` —
+ *     including every method whose line stayed in transpiled coordinates —
  *     produce `coverage: null` and `crap: null`. Callers apply their own
  *     `requireCoverage` policy at the scanner level (`finalizeMethodRows`);
  *     this kernel never decides to skip.
@@ -126,10 +221,12 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
  *   original line resolver; see `methodRowsFromReport`.
  * @returns {Array<{
  *   method: string,
+ *   anonymous: boolean,
  *   startLine: number,
  *   cyclomatic: number,
  *   coverage: number|null,
  *   crap: number|null,
+ *   coordinateSystem: 'original'|'transpiled',
  * }>}
  */
 export function calculateCrapForSource(

package/.agents/scripts/lib/crap-method-identity.js

@@ -0,0 +1,153 @@
+/**
+ * crap-method-identity.js — order-independent identity for the methods an
+ * escomplex report describes (Story #4969).
+ *
+ * Split out of `crap-engine.js` deliberately. That module is the CRAP scoring
+ * kernel — parse, remap a line, join coverage, apply the formula — and naming
+ * a method is a different question from scoring one: it reads the shape of the
+ * scope tree and nothing about coverage or complexity. Keeping the walker here
+ * leaves the kernel's contract ("pure, no I/O, one method in, one score out")
+ * legible instead of half-buried under a tree traversal.
+ */
+
+/**
+ * The label `typhonjs-escomplex-commons` gives a function it cannot name
+ * (Story #4969).
+ *
+ * The `N` is a per-module counter incremented during the AST walk, so it
+ * numbers a function by its *position among its anonymous siblings* rather
+ * than by anything about the function itself. Inserting or deleting one
+ * anonymous function renumbers every later one in the file — and 34.6% of this
+ * repository's CRAP rows were keyed on exactly that. See
+ * `deriveMethodIdentities` for what replaces it.
+ */
+const ESCOMPLEX_ANON_LABEL_RE = /^<anon method-\d+>$/;
+
+/**
+ * True for a `method` value that is a derived anonymous identity rather than a
+ * name the source actually carries — either this module's `<anon …>` identity
+ * or escomplex's superseded ordinal label.
+ *
+ * @param {unknown} method
+ * @returns {boolean}
+ */
+export function isAnonymousMethodLabel(method) {
+  return typeof method === 'string' && method.startsWith('<anon ');
+}
+
+/**
+ * Coerce a method's escomplex line span into a usable numeric pair. A method
+ * missing either bound still has to take a deterministic place in the scope
+ * tree, so it collapses to a zero-width span rather than being dropped: an
+ * identity that varies with how the parser failed would be worse than one that
+ * is merely coarse.
+ *
+ * @param {{lineStart?: unknown, lineEnd?: unknown}} m
+ * @returns {{lineStart: number, lineEnd: number}}
+ */
+function spanOf(m) {
+  const lineStart = Number.isFinite(m?.lineStart) ? m.lineStart : 0;
+  const lineEnd = Number.isFinite(m?.lineEnd) ? m.lineEnd : lineStart;
+  return { lineStart, lineEnd: Math.max(lineStart, lineEnd) };
+}
+
+/**
+ * Give every method in an escomplex report an identity that does not depend on
+ * how many anonymous functions happen to precede it (Story #4969).
+ *
+ * **Named methods are untouched** — their identity is the name escomplex
+ * reported, exactly as before, so no named row is re-keyed by this change.
+ *
+ * **An anonymous method is identified by where it sits, not by when it was
+ * counted.** The identity is `<anon {scope path}>`, where the path is the
+ * chain of enclosing methods from the module down to the method itself. Each
+ * link contributes a name if it has one, otherwise its parameter list plus an
+ * ordinal among the siblings that share *that exact parent and that exact
+ * parameter list*:
+ *
+ * ```text
+ *   <anon (p)#0>                                        module-scope, first (p) arrow
+ *   <anon buildDefaultCrapScorer/(files,opts)#0>        inside a named function
+ *   <anon buildDefaultCrapScorer/(files,opts)#0/(r)#0>  inside that one
+ * ```
+ *
+ * **Why the parameter list and not the body.** The identity has to survive an
+ * edit *to* the method — a method that gains a branch must still be recognised
+ * as the same method, or a genuine complexity regression would read as a brand
+ * new function and score against the new-method ceiling instead of its own
+ * baseline. That rules out anything derived from the body: a source or
+ * normalized-AST hash re-keys the row on the very edit the gate exists to
+ * catch. A parameter list is stable across the edits CRAP measures, and it
+ * partitions same-scope siblings finely enough that the residual ordinal is
+ * almost always `#0`.
+ *
+ * **The residual.** Within one parent *and* one parameter list, siblings are
+ * still told apart by source order, so inserting a same-signature sibling
+ * *before* an existing one still shifts it. That residual is irreducible:
+ * anything that distinguishes two same-scope, same-signature functions has to
+ * read their bodies, and reading their bodies re-keys them on every edit. The
+ * blast radius drops from "every anonymous function in the file" to "the
+ * same-signature siblings of one scope".
+ *
+ * Emission order is load-bearing and guaranteed: escomplex walks the AST
+ * pre-order, so a method's ancestors are always emitted before it. That lets a
+ * single forward pass with an open-ancestor stack resolve every parent in
+ * O(n), and it makes the innermost enclosing method the most recent one still
+ * open.
+ *
+ * @param {Array<object>} methods `report.methods` from escomplex.
+ * @returns {Array<{method: string, anonymous: boolean}>} One entry per input
+ *   method, index-aligned with `methods` and spreadable straight onto a row.
+ *   The scope path itself stays internal — only the identity leaves.
+ */
+export function deriveMethodIdentities(methods) {
+  const identities = [];
+  /** @type {Array<{lineEnd: number, scopePath: string}>} */
+  const openAncestors = [];
+  /** Sibling counts keyed by `parent scope path` + `parameter list`. */
+  const ordinals = new Map();
+
+  for (const m of methods ?? []) {
+    const { lineStart, lineEnd } = spanOf(m);
+    // Close every ancestor whose span has ended before this method begins.
+    while (
+      openAncestors.length > 0 &&
+      openAncestors[openAncestors.length - 1].lineEnd < lineStart
+    ) {
+      openAncestors.pop();
+    }
+    const parentPath =
+      openAncestors.length > 0
+        ? openAncestors[openAncestors.length - 1].scopePath
+        : '';
+
+    const name = typeof m?.name === 'string' ? m.name : '';
+    let segment;
+    let anonymous;
+    if (name === '' || ESCOMPLEX_ANON_LABEL_RE.test(name)) {
+      const params = Array.isArray(m?.paramNames) ? m.paramNames : [];
+      const signature = `(${params.join(',')})`;
+      // NUL separates the two halves because it is the one character a scope
+      // path can never contain — a printable delimiter could be produced by a
+      // parameter name and silently merge two distinct buckets. Spelled as an
+      // escape: a literal NUL byte would make this file binary to git and grep.
+      const bucket = `${parentPath}\u0000${signature}`;
+      const ordinal = ordinals.get(bucket) ?? 0;
+      ordinals.set(bucket, ordinal + 1);
+      segment = `${signature}#${ordinal}`;
+      anonymous = true;
+    } else {
+      segment = name;
+      anonymous = false;
+    }
+
+    const scopePath = parentPath === '' ? segment : `${parentPath}/${segment}`;
+    identities.push({
+      method: anonymous ? `<anon ${scopePath}>` : name,
+      anonymous,
+    });
+    openAncestors.push({ lineEnd, scopePath });
+  }
+
+  return identities;
+}