tumwater 0.4.2 → 0.4.3

package/dist/src/backlog/backlog-structure.js

@@ -215,6 +215,113 @@ export function doubleBlockFixedEntries(md) {
     }
     return found;
 }
+/** The duplicate-heading rule (a): the first `## ` title `head` carries more of than `base` did,
+ * or undefined when none. A base that already carries a duplicate never blocks unrelated edits —
+ * this fires only when the head's count EXCEEDS the base's, so a change that removes a duplicate
+ * always passes. */
+function duplicateSectionReason(file, headCounts, baseCounts) {
+    for (const [title, count] of headCounts)
+        if (count > 1 && count > (baseCounts.get(title) ?? 0))
+            return (`${file} adds another "## ${title}" heading — readers take the first section of a ` +
+                `name, so anything under the duplicate is invisible; keep one "## ${title}" per file`);
+    return undefined;
+}
+/** The dropped-known-section rule (b): the first `## ` title the base carried but `head` dropped,
+ * restricted to this file's KNOWN_SECTIONS, or undefined when none. A `## ` title that is not one
+ * of this file's known sections is not load-bearing: ADDING one is a legitimate project extension
+ * (this repo grew `## Verified`, a doc-only stack can grow `## Notes`), so a new one passes — but
+ * DROPPING one is the repair for a misplaced heading, so this rule guards only known sections and
+ * leaves an unknown one free to be demoted to `### ` under a known section (BUGS.md 2026-10-23). */
+function droppedSectionReason(file, headCounts, baseCounts) {
+    // A `## ` title that is not one of this file's known sections (KNOWN_SECTIONS) is not
+    // load-bearing: ADDING one is a legitimate project extension (this repo grew `## Verified`,
+    // a doc-only stack can grow `## Notes`), so a new one passes — but DROPPING one is the repair
+    // for a misplaced heading, so rule (b) guards only known sections and leaves an unknown one
+    // free to be demoted to `### ` under a known section (BUGS.md 2026-10-23).
+    const known = KNOWN_SECTIONS[file] ?? [];
+    for (const title of baseCounts.keys())
+        if (!headCounts.has(title) && known.includes(title))
+            return (`${file} drops the "## ${title}" section the base had — entries filed under it would ` +
+                `be invisible to every section reader; restore "## ${title}"`);
+    return undefined;
+}
+/** The re-added-archive-heading rule: for PLANS.md's and BUGS.md's archives only, rejects a head
+ * that adds a copy of a `### ` heading the base archive already carries (readdedHeadings) —
+ * finished history pasted back, never a new finished entry — or undefined for every other file.
+ * An archive only grows by new headings: a copy of one the base archive already carries is
+ * finished history pasted back (readdedHeadings), never a new finished entry.
+ */
+function readdedHeadingReason(file, base, head) {
+    if (file === PLANS_ARCHIVE || file === BUGS_ARCHIVE) {
+        const readded = readdedHeadings(base, head);
+        if (readded.length > 0)
+            return (`${file} adds ${plural(readded.length, '"### " heading', '"### " headings')} it already carries ` +
+                `(first: "${truncate(readded[0], 160)}") — the archive holds each finished entry once, so the ` +
+                `copies duplicate its history; remove them, and edit an archived entry in place instead`);
+    }
+    return undefined;
+}
+/** The misplaced-plan rule (part 4/4), for PLANS.md and its archive only, else undefined: rejects
+ * a head that ADDS a `### ` entry directly under `## Done` whose joined heading metadata carries
+ * `(planned YYYY-MM-DD` but no `done YYYY-MM-DD`, and whose key the base's PLANS.md and archive
+ * never carried in ANY section — a plan filed into the wrong section. strandedPlanEntries already
+ * does the fence-aware, joined-metadata reading the first two conditions need; the base's key set
+ * — over both files, since tumwater moves a finished plan from one to the other
+ * (plans/backlog-archive.md) — supplies the third. Judged against the merge-base (the same base
+ * the heading rules use), so a Planned → Done move of an entry the base already had passes and a
+ * pre-existing stranded entry (whose key the base has) never blocks unrelated merges. */
+async function misplacedPlanReason(file, wt, baseRev, base, head) {
+    // Part 4/4's rule, PLANS.md and its archive (see this function's doc comment): a NEW plan
+    // filed directly under ## Done with no done date. strandedPlanEntries already does the
+    // fence-aware, joined-metadata reading the first two conditions need; the base's key set —
+    // over both files, since tumwater moves a finished plan from one to the other
+    // (plans/backlog-archive.md) — supplies the third.
+    if (file === "PLANS.md" || file === PLANS_ARCHIVE) {
+        const baseKeys = new Set([
+            ...planHeadingKeys(file === "PLANS.md" ? base : await fileContentAt(wt, baseRev, "PLANS.md")),
+            ...planHeadingKeys(file === PLANS_ARCHIVE ? base : await fileContentAt(wt, baseRev, PLANS_ARCHIVE)),
+        ]);
+        const newcomer = strandedPlanEntries(head).find((e) => e.section === "Done" && !baseKeys.has(planHeadingKey(e.title)));
+        if (newcomer)
+            // The fault and its fix differ by file: in PLANS.md a NEW plan (the base never carried
+            // it in any section) was pasted under ## Done unfinished and belongs under ## Planned;
+            // in the archive the same heading is a finished plan the commit-time sweep already moved
+            // here, whose only fault is a missing `done YYYY-MM-DD` token — telling its author to
+            // "file it under ## Planned" is the opposite of the fix and wastes a revision.
+            return file === PLANS_ARCHIVE
+                ? `${file} files "${newcomer.title}" directly under "## Done" with no done date — the ` +
+                    `entry is finished and archived, so the only fix is to add \`done YYYY-MM-DD\` to its ` +
+                    `"### " heading; do not move it back under "## Planned"`
+                : `${file} files "${newcomer.title}" directly under "## Done" with no done date — a plan ` +
+                    `written into the done section is invisible to every Planned reader; file it under ` +
+                    `"## Planned" instead`;
+    }
+    return undefined;
+}
+/** The hidden-fixed-record rule, for BUGS.md and its archive only, else undefined: rejects a head
+ * whose multi-block `## Fixed` entries (doubleBlockFixedEntries) the base did not carry — a new
+ * headingless record merged into a neighbor's body — or undefined when none. A new headingless
+ * record cannot hide in a Fixed entry's body: reject a head whose multi-block entries the base did
+ * not carry (an existing one never blocks unrelated edits, matching the heading-set rules above).
+ * The Fix paragraph is the guard's unit, so a merged second block would otherwise sit inside the
+ * neighbor it was symbol-checked against. BUGS-FIXED.md holds the same entries once archived.
+ */
+function hiddenFixedRecordReason(file, base, head) {
+    // A new headingless record cannot hide in a Fixed entry's body: reject a head whose
+    // multi-block entries the base did not carry (an existing one never blocks unrelated
+    // edits, matching the heading-set rules above). The Fix paragraph is the guard's unit, so
+    // a merged second block would otherwise sit inside the neighbor it was symbol-checked
+    // against. BUGS-FIXED.md holds the same entries once archived.
+    if (file === "BUGS.md" || file === BUGS_ARCHIVE) {
+        const baseTitles = new Set(doubleBlockFixedEntries(base));
+        const newcomer = doubleBlockFixedEntries(head).find((title) => !baseTitles.has(title));
+        if (newcomer)
+            return (`${file}'s Fixed entry "${newcomer}" holds more than one **Symptom:**/**Fix:** block — ` +
+                `a record with no "### " heading has merged into it, so the hidden record is invisible ` +
+                `to every section reader; give it its own "### " heading`);
+    }
+    return undefined;
+}
 /** The first structural fault a diff merging into `mainBranch` leaves in a backlog file, or
  * undefined when none: for each touched backlog file it compares the `## ` heading set of the tree
  * being merged (`wt`) against the diff's merge-base — the same base falseFixReason measures
@@ -268,67 +375,13 @@ export async function backlogStructureReason(wt, mainBranch, files) {
         const base = await fileContentAt(wt, baseRev, file);
         const headCounts = sectionTitleCounts(head);
         const baseCounts = sectionTitleCounts(base);
-        for (const [title, count] of headCounts)
-            if (count > 1 && count > (baseCounts.get(title) ?? 0))
-                return (`${file} adds another "## ${title}" heading — readers take the first section of a ` +
-                    `name, so anything under the duplicate is invisible; keep one "## ${title}" per file`);
-        // A `## ` title that is not one of this file's known sections (KNOWN_SECTIONS) is not
-        // load-bearing: ADDING one is a legitimate project extension (this repo grew `## Verified`,
-        // a doc-only stack can grow `## Notes`), so a new one passes — but DROPPING one is the repair
-        // for a misplaced heading, so rule (b) guards only known sections and leaves an unknown one
-        // free to be demoted to `### ` under a known section (BUGS.md 2026-10-23).
-        const known = KNOWN_SECTIONS[file] ?? [];
-        for (const title of baseCounts.keys())
-            if (!headCounts.has(title) && known.includes(title))
-                return (`${file} drops the "## ${title}" section the base had — entries filed under it would ` +
-                    `be invisible to every section reader; restore "## ${title}"`);
-        // An archive only grows by new headings: a copy of one the base archive already carries is
-        // finished history pasted back (readdedHeadings), never a new finished entry.
-        if (file === PLANS_ARCHIVE || file === BUGS_ARCHIVE) {
-            const readded = readdedHeadings(base, head);
-            if (readded.length > 0)
-                return (`${file} adds ${plural(readded.length, '"### " heading', '"### " headings')} it already carries ` +
-                    `(first: "${truncate(readded[0], 160)}") — the archive holds each finished entry once, so the ` +
-                    `copies duplicate its history; remove them, and edit an archived entry in place instead`);
-        }
-        // Part 4/4's rule, PLANS.md and its archive (see this function's doc comment): a NEW plan
-        // filed directly under ## Done with no done date. strandedPlanEntries already does the
-        // fence-aware, joined-metadata reading the first two conditions need; the base's key set —
-        // over both files, since tumwater moves a finished plan from one to the other
-        // (plans/backlog-archive.md) — supplies the third.
-        if (file === "PLANS.md" || file === PLANS_ARCHIVE) {
-            const baseKeys = new Set([
-                ...planHeadingKeys(file === "PLANS.md" ? base : await fileContentAt(wt, baseRev, "PLANS.md")),
-                ...planHeadingKeys(file === PLANS_ARCHIVE ? base : await fileContentAt(wt, baseRev, PLANS_ARCHIVE)),
-            ]);
-            const newcomer = strandedPlanEntries(head).find((e) => e.section === "Done" && !baseKeys.has(planHeadingKey(e.title)));
-            if (newcomer)
-                // The fault and its fix differ by file: in PLANS.md a NEW plan (the base never carried
-                // it in any section) was pasted under ## Done unfinished and belongs under ## Planned;
-                // in the archive the same heading is a finished plan the commit-time sweep already moved
-                // here, whose only fault is a missing `done YYYY-MM-DD` token — telling its author to
-                // "file it under ## Planned" is the opposite of the fix and wastes a revision.
-                return file === PLANS_ARCHIVE
-                    ? `${file} files "${newcomer.title}" directly under "## Done" with no done date — the ` +
-                        `entry is finished and archived, so the only fix is to add \`done YYYY-MM-DD\` to its ` +
-                        `"### " heading; do not move it back under "## Planned"`
-                    : `${file} files "${newcomer.title}" directly under "## Done" with no done date — a plan ` +
-                        `written into the done section is invisible to every Planned reader; file it under ` +
-                        `"## Planned" instead`;
-        }
-        // A new headingless record cannot hide in a Fixed entry's body: reject a head whose
-        // multi-block entries the base did not carry (an existing one never blocks unrelated
-        // edits, matching the heading-set rules above). The Fix paragraph is the guard's unit, so
-        // a merged second block would otherwise sit inside the neighbor it was symbol-checked
-        // against. BUGS-FIXED.md holds the same entries once archived.
-        if (file === "BUGS.md" || file === BUGS_ARCHIVE) {
-            const baseTitles = new Set(doubleBlockFixedEntries(base));
-            const newcomer = doubleBlockFixedEntries(head).find((title) => !baseTitles.has(title));
-            if (newcomer)
-                return (`${file}'s Fixed entry "${newcomer}" holds more than one **Symptom:**/**Fix:** block — ` +
-                    `a record with no "### " heading has merged into it, so the hidden record is invisible ` +
-                    `to every section reader; give it its own "### " heading`);
-        }
+        const reason = duplicateSectionReason(file, headCounts, baseCounts) ??
+            droppedSectionReason(file, headCounts, baseCounts) ??
+            readdedHeadingReason(file, base, head) ??
+            (await misplacedPlanReason(file, wt, baseRev, base, head)) ??
+            hiddenFixedRecordReason(file, base, head);
+        if (reason !== undefined)
+            return reason;
     }
     return undefined;
 }

package/dist/src/backlog/backlog.js

@@ -81,7 +81,7 @@ export function sectionCompletionLags(root, fileName, sectionTitle, dateRe) {
  * because the stamp is the entry's own and the body may name other dates.
  * null when the heading carries no such clause. Routed through backlog-md.ts's firstDate -
  * the one first-match mechanism - with this module's own stamp regex.
- * questionFilingDate (question-answer.ts) is the same recipe for the `asked by` verb. */
+ * questionFilingDate (backlog-question-answer.ts) is the same recipe for the `asked by` verb. */
 const STAMP_DATE_RE = /(?:planned|reported|found by)\b[^)]*?\b(\d{4}-\d{2}-\d{2})/;
 export function filingDate(title) {
     return firstDate(title, STAMP_DATE_RE);

package/dist/src/baseline/main-baseline.js

@@ -86,29 +86,44 @@ export function persistBaselineVerdicts(root) {
     const file = baselineVerdictsPath(root);
     greensFile = undefined; // the load below re-writes nothing it just read
     const stored = readJsonFile(file);
-    const entries = Array.isArray(stored?.greens) ? stored.greens : [];
-    for (const entry of entries) {
-        if (!isJsonObject(entry) || typeof entry.sha !== "string" || !/^[0-9a-f]{40,64}$/.test(entry.sha))
-            continue;
-        if (baselineCache.has(entry.sha))
-            continue;
-        const from = typeof entry.inheritedFrom === "string" ? { inheritedFrom: entry.inheritedFrom } : {};
-        rememberBaseline(entry.sha, { status: "green", sha: entry.sha, ...from });
-    }
-    const reds = Array.isArray(stored?.reds) ? stored.reds : [];
-    for (const entry of reds) {
-        if (!isJsonObject(entry) || typeof entry.sha !== "string" || !/^[0-9a-f]{40,64}$/.test(entry.sha))
-            continue;
-        if (baselineCache.has(entry.sha))
-            continue;
-        const failingTests = Array.isArray(entry.failingTests)
-            ? entry.failingTests.filter((t) => typeof t === "string")
-            : [];
-        const script = typeof entry.script === "string" ? { script: entry.script } : {};
-        rememberBaseline(entry.sha, { status: "red", sha: entry.sha, ...script, failingTests });
-    }
+    for (const entry of storedVerdictList(stored, "greens"))
+        restoreGreenVerdict(entry);
+    for (const entry of storedVerdictList(stored, "reds"))
+        restoreRedVerdict(entry);
     greensFile = file;
 }
+/** The saved array for one kind of verdict, or an empty list when absent or not an array. */
+function storedVerdictList(stored, key) {
+    const value = stored?.[key];
+    return Array.isArray(value) ? value : [];
+}
+/** A saved entry that is an object with a 40-64 hex `sha`, or null when it is not. */
+function storedVerdictEntry(entry) {
+    if (!isJsonObject(entry))
+        return null;
+    if (typeof entry.sha !== "string" || !/^[0-9a-f]{40,64}$/.test(entry.sha))
+        return null;
+    return entry;
+}
+/** Restore one saved green, carrying an optional `inheritedFrom`, unless the cache holds it. */
+function restoreGreenVerdict(entry) {
+    const parsed = storedVerdictEntry(entry);
+    if (parsed === null || baselineCache.has(parsed.sha))
+        return;
+    const from = typeof parsed.inheritedFrom === "string" ? { inheritedFrom: parsed.inheritedFrom } : {};
+    rememberBaseline(parsed.sha, { status: "green", sha: parsed.sha, ...from });
+}
+/** Restore one saved red: optional `script` and failing tests, unless the cache holds it. */
+function restoreRedVerdict(entry) {
+    const parsed = storedVerdictEntry(entry);
+    if (parsed === null || baselineCache.has(parsed.sha))
+        return;
+    const failingTests = Array.isArray(parsed.failingTests)
+        ? parsed.failingTests.filter((t) => typeof t === "string")
+        : [];
+    const script = typeof parsed.script === "string" ? { script: parsed.script } : {};
+    rememberBaseline(parsed.sha, { status: "red", sha: parsed.sha, ...script, failingTests });
+}
 /** In-flight dedup: concurrent runs on the same not-yet-cached SHA (a fresh main move wakes
  * every role's verifier at once) share one check run instead of racing N npm invocations. Keyed by
  * SHA for ordinary checks; a re-verification adds its worktree, because joining another
@@ -350,76 +365,22 @@ tier = CHECK_TIER.other) {
     const sha = await refSha(wt, "HEAD");
     if (!sha)
         return { baseline: null }; // No HEAD (unborn branch) — nothing to key on.
-    const stored = baselineCache.get(sha);
-    const cached = observedOnly && stored?.inheritedFrom !== undefined ? undefined : stored;
-    if (cached && !forceFresh && !shouldRerunRed(cached, wt, reverifyRed))
+    const { cached, key } = cachedBaselineFor(sha, wt, { reverifyRed, observedOnly, forceFresh });
+    if (cached)
         return { baseline: cached };
-    if (!cached && !forceFresh && !observedOnly) {
+    // A re-run of a red keys the in-flight map by worktree (key !== sha): joining another
+    // worktree's run would observe the environment this run exists to re-test, and it is not a
+    // carry-over candidate either — only a SHA with no cached verdict may inherit a green.
+    if (!forceFresh && !observedOnly && key === sha) {
         // Outside the in-flight dedup below on purpose: a forceFresh or observedOnly caller joining
         // a pending promise must get a run, never a carried-over verdict.
-        const exempt = exemptPathsOf(config);
-        const inherited = exempt.length > 0 ? await inheritedGreen(wt, sha, exempt) : null;
-        if (inherited) {
-            // Re-read after the await: a run that settled meanwhile knows more than the carry-over.
-            const settled = baselineCache.get(sha);
-            if (settled)
-                return { baseline: settled };
-            rememberBaseline(sha, inherited);
+        const inherited = await inheritedBaselineFor(wt, sha, config);
+        if (inherited)
             return { baseline: inherited };
-        }
     }
-    // A re-run of a red keys the in-flight map by worktree: joining another worktree's run would
-    // observe the environment this run exists to re-test.
-    const key = cached?.status === "red" ? `${sha}\u0000${wt}` : sha;
     let pending = baselineInFlight.get(key);
     if (!pending) {
-        pending = (async () => {
-            const check = detectBuildCheck(wt, config);
-            if (!check)
-                return { baseline: null }; // No declared check — nothing to verify, nothing to block on.
-            // The same process-wide check permit the scoped checks take (build/build-check.ts's
-            // withCheckPermit): this runs the suite directly, so it must count against the cap too.
-            // Only the one run per key holds a permit; deduped waiters above await `pending` holding
-            // none.
-            const { outcome, durationMs } = await withCheckPermit(config, tier, () => runWithCleanRetry(() => runBuildCheck(wt, check, undefined, undefined, sampleSleep), 
-            // Weather (a late deadline, a foreign kill, a host sleep) made no verdict about the
-            // tree: the first attempt is priced as its own run, and the retry's outcome stands —
-            // the same rule runScopedBuildCheck applies at every other scope.
-            (first, dur) => onRun?.({ outcome: first, durationMs: dur })), undefined, "main baseline");
-            onRun?.({ outcome, durationMs });
-            if (outcome.status === "skipped") {
-                // Environmental (timeout/no-npm), after the clean retry above for weather shapes:
-                // warn-and-proceed semantics like the gate's pre-check; never cache red for a skip.
-                return { baseline: null, skipReason: outcome.skipReason, run: outcome.run };
-            }
-            if (outcome.status === "failed" && (outcome.run?.sleptMs ?? 0) > SLEEP_SPAN_TOLERANCE_MS) {
-                // A failure the host slept through made no verdict about the tree either (BUGS.md
-                // 2026-09-30): the sleep expired a test's own wall-clock wait at the wake and the suite
-                // exited 1 inside the deadline. Caching it red would make sleep weather the team's
-                // authoritative red main, so nothing is cached — the next consult re-runs, and a clean
-                // verdict then settles the SHA exactly as before.
-                return { baseline: null, run: outcome.run, unverified: true };
-            }
-            const prior = baselineCache.get(sha);
-            const priorRedFrom = prior?.status === "red" ? (prior.redFrom ?? []) : [];
-            const baseline = outcome.status === "passed"
-                ? { status: "green", sha }
-                : {
-                    status: "red",
-                    sha,
-                    script: outcome.script,
-                    outputTail: outcome.outputTail,
-                    failingTests: outcome.failingTests ?? [],
-                    redFrom: priorRedFrom.includes(wt) ? priorRedFrom : [...priorRedFrom, wt],
-                };
-            // A green is always recorded (promoting a provisional red); a red never overwrites an
-            // observed green — a concurrent run may have promoted this SHA while this one was still
-            // going. An inherited green is no observation, so this run's verdict replaces it either way.
-            const current = baselineCache.get(sha);
-            if (current?.status !== "green" || current.inheritedFrom !== undefined)
-                rememberBaseline(sha, baseline);
-            return { baseline };
-        })();
+        pending = runBaselineOnce(sha, wt, config, onRun, sampleSleep, tier);
         baselineInFlight.set(key, pending);
     }
     try {
@@ -430,6 +391,109 @@ tier = CHECK_TIER.other) {
             baselineInFlight.delete(key);
     }
 }
+/** The usable cached verdict for `sha` — or null when the suite must run — together with the
+ * in-flight key its run dedups on. Applies the observedOnly inherited-green filter, the
+ * forceFresh / red re-run short-circuit, and the worktree-qualified key a red re-run keys by.
+ * `key === sha` tells the caller the SHA had no verdict to re-run (a possible carry-over
+ * candidate); a worktree-qualified key is a pending red re-run, which never inherits. */
+function cachedBaselineFor(sha, wt, opts) {
+    const stored = baselineCache.get(sha);
+    const cached = opts.observedOnly && stored?.inheritedFrom !== undefined ? undefined : stored;
+    const usable = cached && !opts.forceFresh && !shouldRerunRed(cached, wt, opts.reverifyRed) ? cached : null;
+    const key = cached?.status === "red" ? `${sha}\u0000${wt}` : sha;
+    return { cached: usable, key };
+}
+/** The inherited green for `sha` across review-exempt ancestors, or null when there is none to
+ * carry over. The exemptPathsOf(config) + inheritedGreen(wt, sha, exempt) walk, the post-await
+ * cache re-read (a run that settled meanwhile knows more than the carry-over), and the
+ * rememberBaseline re-seed of the carried-over verdict. */
+async function inheritedBaselineFor(wt, sha, config) {
+    const exempt = exemptPathsOf(config);
+    const inherited = exempt.length > 0 ? await inheritedGreen(wt, sha, exempt) : null;
+    if (inherited) {
+        // Re-read after the await: a run that settled meanwhile knows more than the carry-over.
+        const settled = baselineCache.get(sha);
+        if (settled)
+            return settled;
+        rememberBaseline(sha, inherited);
+        return inherited;
+    }
+    return null;
+}
+/** Run the declared check once under the same process-wide check permit the scoped checks take,
+ * retrying once when the first attempt made no verdict about the tree (a late deadline, a
+ * foreign kill, a host sleep). Returns the outcome and its duration, or null when no check is
+ * declared (nothing to verify, nothing to block on). */
+async function detectedBaselineOutcome(wt, config, onRun, sampleSleep, tier) {
+    const check = detectBuildCheck(wt, config);
+    if (!check)
+        return null; // No declared check — nothing to verify, nothing to block on.
+    // The same process-wide check permit the scoped checks take (build/build-check.ts's
+    // withCheckPermit): this runs the suite directly, so it must count against the cap too.
+    // Only the one run per key holds a permit; deduped waiters above await `pending` holding
+    // none.
+    return withCheckPermit(config, tier, () => runWithCleanRetry(() => runBuildCheck(wt, check, undefined, undefined, sampleSleep), 
+    // Weather (a late deadline, a foreign kill, a host sleep) made no verdict about the
+    // tree: the first attempt is priced as its own run, and the retry's outcome stands —
+    // the same rule runScopedBuildCheck applies at every other scope.
+    (first, dur) => onRun?.({ outcome: first, durationMs: dur })), undefined, "main baseline");
+}
+/** Build the green/red verdict from a run's outcome, folding the prior red's observed worktrees
+ * (redFrom) into a fresh red. Does not write the cache — the caller decides whether to promote. */
+function baselineFromOutcome(sha, wt, outcome) {
+    const prior = baselineCache.get(sha);
+    const priorRedFrom = prior?.status === "red" ? (prior.redFrom ?? []) : [];
+    return outcome.status === "passed"
+        ? { status: "green", sha }
+        : {
+            status: "red",
+            sha,
+            script: outcome.script,
+            outputTail: outcome.outputTail,
+            failingTests: outcome.failingTests ?? [],
+            redFrom: priorRedFrom.includes(wt) ? priorRedFrom : [...priorRedFrom, wt],
+        };
+}
+/** Persist a freshly-run verdict unless a concurrent run already promoted the SHA with an
+ * observed green. A green is always recorded (promoting a provisional red); a red never
+ * overwrites an observed green — a concurrent run may have promoted this SHA while this one was
+ * still going. An inherited green is no observation, so this run's verdict replaces it either
+ * way. */
+function rememberPromotableBaseline(sha, baseline) {
+    // A green is always recorded (promoting a provisional red); a red never overwrites an
+    // observed green — a concurrent run may have promoted this SHA while this one was still
+    // going. An inherited green is no observation, so this run's verdict replaces it either way.
+    const current = baselineCache.get(sha);
+    if (current?.status !== "green" || current.inheritedFrom !== undefined)
+        rememberBaseline(sha, baseline);
+}
+/** Run the suite once for `sha` at `wt`: detect the check, run it under the permit with a clean
+ * retry and its two onRun calls, fold the outcome into a verdict — skips and slept-through
+ * failures return no verdict and write nothing — and promote it unless an observed green
+ * outranks it. This replaces the old `(async () => …)()` closure stored in the in-flight map. */
+async function runBaselineOnce(sha, wt, config, onRun, sampleSleep, tier) {
+    const detected = await detectedBaselineOutcome(wt, config, onRun, sampleSleep, tier);
+    if (!detected)
+        return { baseline: null };
+    const { outcome, durationMs } = detected;
+    onRun?.({ outcome, durationMs });
+    if (outcome.status === "skipped") {
+        // Environmental (timeout/no-npm), after the clean retry above for weather shapes:
+        // warn-and-proceed semantics like the gate's pre-check; never cache red for a skip.
+        return { baseline: null, skipReason: outcome.skipReason, run: outcome.run };
+    }
+    if (outcome.status === "failed" && (outcome.run?.sleptMs ?? 0) > SLEEP_SPAN_TOLERANCE_MS) {
+        // A failure the host slept through made no verdict about the tree either (BUGS.md
+        // 2026-09-30): the sleep expired a test's own wall-clock wait at the wake and the suite
+        // exited 1 inside the deadline. Caching it red would make sleep weather the team's
+        // authoritative red main, so nothing is cached — the next consult re-runs, and a clean
+        // verdict then settles the SHA exactly as before.
+        return { baseline: null, run: outcome.run, unverified: true };
+    }
+    const baseline = baselineFromOutcome(sha, wt, outcome);
+    rememberPromotableBaseline(sha, baseline);
+    return { baseline };
+}
 /** Is main green at the mirror worktree's HEAD? The merge path seeds a green verdict for every
  * merged code SHA (noteGreenBaseline — its in-lock post-rebase re-check, or the gate's pre-check
  * when the rebase was a no-op), so the common case is a cache hit. A head that only added doc