tumwater 0.4.2 → 0.4.4

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

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

@@ -13,7 +13,7 @@
  * Both take an injected `now` so tests never read the clock. */
 import { readEventsSince } from "../events/event-window.js";
 import { loadQuarantine } from "../review/known-flakes.js";
-import { DAY_MS, clockHm, humanAgo } from "../text/datetime.js";
+import { DAY_MS, HOUR_MS, clockHm, humanAgo } from "../text/datetime.js";
 import { shortSha } from "../text/format.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { plural } from "../text/phrases.js";
@@ -193,5 +193,5 @@ function redDurationPhrase(ms) {
     const minutes = Math.round(ms / 60_000);
     if (minutes < 24 * 60)
         return `${minutes} min`;
-    return `${Math.round(ms / 3_600_000)} h`;
+    return `${Math.round(ms / HOUR_MS)} h`;
 }

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

@@ -1,3 +1,4 @@
+import { distinctOrdered } from "../collections.js";
 import { checkMainBaseline } from "./main-baseline.js";
 import { baselineCheckLogger, clearHealKeyOnGreen, withMainTipWorktree } from "./main-red.js";
 import { CHECK_TIER } from "../concurrency/check-permit.js";
@@ -13,6 +14,22 @@ import { treeDiffFiles } from "../git/git-diff.js";
 import { mergingRoleOf } from "../events/event-read.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { diffRuleReasons } from "../review/diff-rules.js";
+/** The main_check event payload for a settled verdict: the baseline sha and status, the run
+ * duration (0 when nothing ran), the covered-commit count, and, on a red, the failing tests and
+ * the quarantined-only marker. */
+function mainCheckEvent(baseline, red, quarantined, covered, durationMs) {
+    return {
+        source: TUMWATER_SOURCE,
+        type: "main_check",
+        sha: baseline.sha,
+        status: red ? "failed" : "passed",
+        durationMs,
+        covered,
+        ...(red ? { failingTests: baseline.failingTests ?? [] } : {}),
+        ...(quarantined ? { quarantined } : {}),
+        ...(baseline.inheritedFrom !== undefined ? { inherited: true } : {}),
+    };
+}
 /** The failing tests of each root's newest watch verdict, keyed by root. */
 const knownFailures = new Map();
 /** Main's known failures: the failing tests of the watch's newest verdict — main's tip, or the
@@ -20,7 +37,7 @@ const knownFailures = new Map();
  * (review/known-flakes.ts). Empty when the verdict is green, red with no parsed test, or none has
  * been recorded yet in this process, and nothing is quarantined. */
 export function knownMainFailures(root) {
-    return [...new Set([...(knownFailures.get(root) ?? []), ...quarantinedTests(root)])];
+    return distinctOrdered([...(knownFailures.get(root) ?? []), ...quarantinedTests(root)]);
 }
 /** The failing tests of a failed check when every one of them is a known main failure; null when
  * the output names no test, any test is outside the known set, or none is known. A list at
@@ -76,8 +93,9 @@ export function createMainWatch(root, mainBranch, onCulprit) {
         }
     }
     async function watchOnce(mainHead, config) {
-        // The deterministic diff rules ("Every commit is verified on main, part 1/3"): run the same
-        // five checks the gate runs on a change, against main's new tip. A rule failure is a
+        // The deterministic diff rules ("Every commit is verified on main, part 1/3"): run the full
+        // five-check set the watch and gate share — the gate now runs only the three a later commit
+        // cannot repair — against main's new tip. A rule failure is a
         // deterministic red — it takes no confirming re-run and never quarantines — reported as a
         // warning naming the rule and the head (and each committing role, when a recent merged event
         // names one). It runs on every tip the watch covers in a poll — a build green, a build
@@ -106,7 +124,7 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 await git(wt, "checkout", "-q", "--detach", "--force", commit);
                 const parent = `${commit}^`;
                 const files = (await treeDiffFiles(wt, parent, commit)) ?? [];
-                const [ruleReason] = await diffRuleReasons(wt, parent, files, mergingRoleOf(root, commit) ?? "", isExemptDiff(files, config.review.exemptPaths));
+                const [ruleReason] = await diffRuleReasons(wt, parent, files, mergingRoleOf(root, commit) ?? "", isExemptDiff(files, config.review.exemptPaths), "watch");
                 if (ruleReason !== undefined) {
                     logEventBestEffort(root, {
                         source: TUMWATER_SOURCE,
@@ -120,17 +138,11 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 }
             }
         };
-        if (!detectBuildCheck(root, config)) {
-            // No declared build check: nothing to watch for a build red, but the diff rules still run on
-            // the tip. The build-red path below is what never runs here.
-            await withMainTipWorktree(root, mainBranch, async (wt) => {
-                await watchRules(wt, lastWatched, await headOf(wt));
-            });
-            lastWatched = mainHead; // no declared check: nothing else to watch until main moves
-            return;
-        }
-        await withMainTipWorktree(root, mainBranch, async (wt) => {
-            const started = Date.now();
+        /** Run the declared build check on main's tip, re-running a red once and quarantining a flake
+         * whose re-run turns green. Returns the check's result and whether any run actually executed
+         * (false for a cache hit, a skip, or a sleep-spanned run). `config` and `root` are captured
+         * from `watchOnce`. */
+        async function runBaselineCheck(wt) {
             let ran = false;
             const onRun = baselineCheckLogger(root, TUMWATER_SOURCE);
             const hook = (run) => {
@@ -145,45 +157,31 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 if (check.baseline?.status === "green")
                     quarantineTests(root, first.failingTests, (first.failingTests ?? []).join("\n"));
             }
-            const baseline = check.baseline;
-            const previous = lastWatched;
-            // A skipped or sleep-spanned run made no verdict: the head still counts as watched, so the
-            // next poll does not start another run for it — but the diff rules still run on this tip.
-            if (!baseline) {
-                const tip = await headOf(wt);
-                await watchRules(wt, previous, tip);
-                return void (lastWatched = tip);
-            }
-            lastWatched = baseline.sha;
+            return { check, ran };
+        }
+        /** The covered-commit count for a main_check event: the first-parent commits between the
+         * previous and new watched heads, or 1 when there is no previous head. */
+        async function countCovered(wt, previous, sha) {
+            if (previous === undefined)
+                return 1;
+            const counted = Number(((await gitTry(wt, "rev-list", "--first-parent", "--count", `${previous}..${sha}`)) ?? "").trim());
+            return Number.isFinite(counted) && counted > 0 ? counted : 1;
+        }
+        /** Settle the verdict for a checked baseline: distinguish quarantined-only reds, record
+         * main's known failures, count the covered commits, and log the main_check event. Returns
+         * whether the tip settled red (a red naming tests that are not all quarantined). */
+        async function recordMainCheck(wt, baseline, previous, ran, started) {
             // A red naming only quarantined tests counts as green: no redeploy hold.
             const quarantined = baseline.status === "red" ? onlyQuarantined(root, baseline.failingTests) : null;
             const red = baseline.status === "red" && !quarantined;
             knownFailures.set(root, red ? (baseline.failingTests ?? []) : []);
-            const counted = previous === undefined
-                ? 1
-                : Number(((await gitTry(wt, "rev-list", "--first-parent", "--count", `${previous}..${baseline.sha}`)) ?? "").trim());
-            logEventBestEffort(root, {
-                source: TUMWATER_SOURCE,
-                type: "main_check",
-                sha: baseline.sha,
-                status: red ? "failed" : "passed",
-                durationMs: ran ? Date.now() - started : 0,
-                covered: Number.isFinite(counted) && counted > 0 ? counted : 1,
-                ...(red ? { failingTests: baseline.failingTests ?? [] } : {}),
-                ...(quarantined ? { quarantined } : {}),
-                ...(baseline.inheritedFrom !== undefined ? { inherited: true } : {}),
-            });
-            // The diff rules judge the tip whether the build is green or red; the build-red path below
-            // names the whole tip as the culprit, so the two red kinds are judged independently.
-            await watchRules(wt, previous, baseline.sha);
-            // A settled non-red verdict (a green, or a red naming only quarantined tests) clears the
-            // heal-dedup key, so a failing set that returns after a green main is healed again. A
-            // settled red verdict below does NOT clear it: the heal-dedup key stays set while main
-            // is red.
-            if (!red) {
-                clearHealKeyOnGreen();
-                return;
-            }
+            const covered = await countCovered(wt, previous, baseline.sha);
+            logEventBestEffort(root, mainCheckEvent(baseline, red, quarantined, covered, ran ? Date.now() - started : 0));
+            return red;
+        }
+        /** Name a settled red tip as the culprit: its merging runner, the main_culprit event, and
+         * the onCulprit callback with the tip and its failing tests. */
+        function reportCulprit(baseline) {
             // The newest head is the culprit ("Every commit is verified on main, part 2/3"): the watch
             // checks each new red tip, so whatever it found belongs to the head it checked. Once per red
             // head — lastWatched already holds it, so a later poll does not attribute it again — name
@@ -201,6 +199,42 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 failingTests: baseline.failingTests ?? [],
                 tip: baseline.sha,
             });
+        }
+        if (!detectBuildCheck(root, config)) {
+            // No declared build check: nothing to watch for a build red, but the diff rules still run on
+            // the tip. The build-red path below is what never runs here.
+            await withMainTipWorktree(root, mainBranch, async (wt) => {
+                await watchRules(wt, lastWatched, await headOf(wt));
+            });
+            lastWatched = mainHead; // no declared check: nothing else to watch until main moves
+            return;
+        }
+        await withMainTipWorktree(root, mainBranch, async (wt) => {
+            const started = Date.now();
+            const { check, ran } = await runBaselineCheck(wt);
+            const baseline = check.baseline;
+            const previous = lastWatched;
+            // A skipped or sleep-spanned run made no verdict: the head still counts as watched, so the
+            // next poll does not start another run for it — but the diff rules still run on this tip.
+            if (!baseline) {
+                const tip = await headOf(wt);
+                await watchRules(wt, previous, tip);
+                return void (lastWatched = tip);
+            }
+            lastWatched = baseline.sha;
+            const red = await recordMainCheck(wt, baseline, previous, ran, started);
+            // The diff rules judge the tip whether the build is green or red; the build-red path below
+            // names the whole tip as the culprit, so the two red kinds are judged independently.
+            await watchRules(wt, previous, baseline.sha);
+            // A settled non-red verdict (a green, or a red naming only quarantined tests) clears the
+            // heal-dedup key, so a failing set that returns after a green main is healed again. A
+            // settled red verdict below does NOT clear it: the heal-dedup key stays set while main
+            // is red.
+            if (!red) {
+                clearHealKeyOnGreen();
+                return;
+            }
+            reportCulprit(baseline);
         });
     }
     return {

package/dist/src/brief/brief.js

@@ -106,16 +106,10 @@ export function briefFile(root) {
  * on-purpose bare repo. An unreadable candidate counts: a brief that cannot be read is one
  * the roles cannot use, and the underlying firstBriefText throw is caught and reported as
  * true here — same subset doctor's `brief` warn covers, minus the bare-repo state that
- * doctor deems fine. Consumer: src/status/status-data.ts's snapshot. */
+ * doctor deems fine. Thin accessor over briefStatus, so this predicate and the snapshot's
+ * shared flags share one implementation. */
 export function briefBlockMissing(root) {
-    if (briefCandidates(root).every((candidate) => !fs.existsSync(candidate)))
-        return false;
-    try {
-        return (readBrief(root)?.prompt ?? "") === "";
-    }
-    catch {
-        return true;
-    }
+    return briefStatus(root).missing;
 }
 /** True when the resolved brief block exceeds the read cap (BRIEF_TEXT_MAX_CHARS) — the
  * always-on amber twin of the doctor `brief` row's over-cap warn. extractPrompt truncates
@@ -127,15 +121,34 @@ export function briefBlockMissing(root) {
  * a surrogate pair, while an at-cap block stays equal to it. A repo with no candidate
  * resolves null (0, false), and an unreadable candidate's readBrief throw is caught to false,
  * because briefBlockMissing already raises `no-brief` for that state; an empty block stays
- * briefBlockMissing's (its resolved length is 0). Consumer: src/status/status-data.ts's
- * snapshot. */
+ * briefBlockMissing's (its resolved length is 0). Thin accessor over briefStatus, so this
+ * predicate and the snapshot's shared flags share one implementation. */
 export function briefBlockOverCap(root) {
+    return briefStatus(root).overCap;
+}
+/** The always-on brief degraded-state flags, derived from ONE candidate scan and ONE file
+ * read — the per-second status snapshot's `noBrief`/`briefTruncated` fields, and the single
+ * implementation of both predicates: the standalone briefBlockMissing/briefBlockOverCap
+ * accessors delegate here, so the shared and standalone paths cannot disagree. The snapshot
+ * used to call those two accessors, each calling readBrief — which re-lists both candidates
+ * and re-reads the whole brief file — twice per poll, on a file that changes only when a role
+ * edits it. briefStatus is the degraded-state twin of readBrief's promise (briefFile +
+ * readBriefText derive from one scan): the two flags share one read, and each flag applies the
+ * value's own predicate. `missing` is true when a candidate exists but none resolves a
+ * non-empty block (or the resolving read threw); `overCap` true when the resolved block
+ * exceeds the cap. A repo with no candidate at all is neither (both false). */
+export function briefStatus(root) {
+    if (briefCandidates(root).every((candidate) => !fs.existsSync(candidate))) {
+        return { missing: false, overCap: false };
+    }
+    let prompt = "";
     try {
-        return (readBrief(root)?.prompt.length ?? 0) > BRIEF_TEXT_MAX_CHARS;
+        prompt = readBrief(root)?.prompt ?? "";
     }
     catch {
-        return false;
+        return { missing: true, overCap: false }; // Unreadable — the briefBlockMissing subset.
     }
+    return { missing: prompt === "", overCap: prompt.length > BRIEF_TEXT_MAX_CHARS };
 }
 /** The project's brief text, extracted from the resolved brief file's managed section —
  * TUMWATER.md when it exists with markers, else README.md (plans/portability.md §7a/7). The