tumwater 0.2.0 → 0.3.0

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 import { runBuildCheck, } from "../build/build-check.js";
 import { SLEEP_SPAN_TOLERANCE_MS, runWithCleanRetry } from "../build/build-check-events.js";
 import { sampleSleepClock } from "../build/host-sleep.js";
@@ -10,7 +9,7 @@ import { treeDiffFiles } from "../git/git-diff.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { isJsonObject } from "../files/json-object.js";
-import { baselineVerdictsPath } from "../paths.js";
+import { baselineVerdictsPath, mirrorWorktreePath } from "../paths.js";
 import { memoSetLru } from "../collections.js";
 /** Team-shared verdict cache, keyed by main SHA. In-memory only: after a restart the cache is cold
  * and one re-check per red SHA happens — cheap and deterministic, mirroring the budget gate's
@@ -50,14 +49,18 @@ function rememberBaseline(sha, baseline) {
     memoSetLru(baselineCache, sha, baseline, BASELINE_CACHE_MAX);
     saveGreens();
 }
-/** The file the cache's greens are mirrored to (persistBaselineVerdicts), or undefined while no
+/** How many reds the verdict file keeps (the newest). */
+const SAVED_REDS_MAX = 64;
+/** The file the cache's verdicts are mirrored to (persistBaselineVerdicts), or undefined while no
  * team process has asked for it: the CLI and the tests keep the cache in memory only. */
 let greensFile;
-/** Mirror the green verdicts to disk, so the team's next generation starts with them. A restart
- * used to empty the cache, and the first tick after every restart re-ran the suite on a main the
+/** Mirror the verdicts to disk, so the team's next generation starts with them. A restart
+ * used to empty the cache, and the first run after every restart re-ran the suite on a main the
  * previous generation had already verified (41 of 319 baseline runs over 2026-10-02..12 started
- * within 10 minutes of an orchestrator start). Only greens are kept: a green is a fact about an
- * immutable tree, while a red is provisional (shouldRerunRed) and is cheap to rediscover. Best
+ * within 10 minutes of an orchestrator start). A green is a fact about an
+ * immutable tree. A red is provisional (shouldRerunRed), so it is saved only as the main watch's
+ * record — sha, script and failing tests, the newest SAVED_REDS_MAX — and a loaded red is
+ * re-run by the next worktree that consults it, like any red seen in one worktree. Best
  * effort: a failed write costs at most a re-run after the next restart. */
 function saveGreens() {
     if (greensFile === undefined)
@@ -65,15 +68,19 @@ function saveGreens() {
     const greens = [...baselineCache.values()]
         .filter((b) => b.status === "green")
         .map((b) => (b.inheritedFrom === undefined ? { sha: b.sha } : { sha: b.sha, inheritedFrom: b.inheritedFrom }));
+    const reds = [...baselineCache.values()]
+        .filter((b) => b.status === "red")
+        .slice(-SAVED_REDS_MAX)
+        .map((b) => ({ sha: b.sha, script: b.script, failingTests: b.failingTests ?? [] }));
     try {
-        writeJsonAtomic(greensFile, { greens });
+        writeJsonAtomic(greensFile, { greens, reds });
     }
     catch {
         // A read-only or full disk: the in-memory cache still answers this generation.
     }
 }
-/** Load the green verdicts a previous generation saved under `root` and keep mirroring them
- * there (saveGreens). Called once at team startup (cli/cli-run.ts). An entry the cache already
+/** Load the verdicts a previous generation saved under `root` and keep mirroring them
+ * there (saveGreens). Called once at team startup (cli/cli-start.ts). An entry the cache already
  * holds is left as it is, and a malformed file or entry reads as no data. */
 export function persistBaselineVerdicts(root) {
     const file = baselineVerdictsPath(root);
@@ -88,9 +95,21 @@ export function persistBaselineVerdicts(root) {
         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 });
+    }
     greensFile = file;
 }
-/** In-flight dedup: concurrent ticks on the same not-yet-cached SHA (a fresh main move wakes
+/** In-flight dedup: concurrent runs on the same not-yet-cached SHA (a fresh main move wakes
  * every blocked role 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
  * worktree's run would observe the wrong environment — the one thing it exists to re-test. */
@@ -98,7 +117,7 @@ const baselineInFlight = new Map();
 /** Should a cached RED be re-run here instead of trusted? A red says as much about the
  * environment the check ran in as about the tree — a worktree mid-install, or a machine under
  * the load the team deliberately creates starving a timing-sensitive test (BUGS.md's
- * load-sensitive tests entry). The role loops consult this team-shared cache and, before
+ * load-sensitive tests entry). The role runners consult this team-shared cache and, before
  * 2026-09-18, trusted a red forever: one environmental red blocked every code role until main
  * moved, and main could not move, because blocking the code roles is exactly what stops it —
  * a deadlock broken only by restarting the orchestrator, since the cache is per-process.
@@ -126,9 +145,9 @@ function shouldRerunRed(cached, wt, reverifyRed) {
  * scope-`batch` check ran green on exactly it (a skipped check seeds nothing, and neither does a
  * merge_blocked stack or a doc-only re-stack that merged without a check of its own). Seeding
  * here means that once the merge completes — main now points at this very SHA — the next fresh
- * tick's checkMainBaseline is a cache hit instead of re-running the full suite on an
+ * run's checkMainBaseline is a cache hit instead of re-running the full suite on an
  * already-verified tree: for tumwater itself that saves one redundant `npm test` (~1 min) per
- * merged code tick, plus every other role waking on "main moved" stalling behind that in-flight
+ * merged code run, plus every other role waking on "main moved" stalling behind that in-flight
  * run. Never seed a pre-rebase head: whenever main moved under the review, that SHA never
  * becomes main and the entry would silently miss (BUGS.md 2026-09-08). Safe because git trees
  * are immutable — a SHA's content cannot change under a cached verdict, the same staleness
@@ -197,8 +216,55 @@ function exemptPathsOf(config) {
 export function cachedBaselineVerdict(sha) {
     return baselineCache.get(sha)?.status;
 }
+/** The main watch's newest verdict for `sha` (default: `wt`'s HEAD) or its nearest first-parent
+ * ancestor the cache holds one for — looking at most INHERIT_WALK_MAX commits down — WITHOUT
+ * running anything; null when there is none. With `check.mergeCommand` set no merge seeds the
+ * cache, so every verdict in it is a full check the watch (main-watch.ts) or another consumer
+ * ran, or a doc-only inheritance of one, and the red-main reads (main-red.ts) answer from here
+ * rather than start a full check. Never throws: a git failure reads as no verdict. */
+export async function watchedBaseline(wt, sha) {
+    const tip = sha ?? (await refSha(wt, "HEAD"));
+    if (!tip)
+        return null;
+    const own = baselineCache.get(tip);
+    if (own)
+        return own;
+    const ancestors = gitLines(await gitTry(wt, "rev-list", "--first-parent", `--max-count=${INHERIT_WALK_MAX}`, `${tip}^`));
+    for (const ancestor of ancestors) {
+        const verdict = baselineCache.get(ancestor);
+        if (verdict)
+            return verdict;
+    }
+    return null;
+}
+/** How many first-parent commits below main's tip redeployTarget looks at. */
+const REDEPLOY_WALK_MAX = 64;
+/** The commit self-redeploy should run: main's newest first-parent commit with a green full-check
+ * verdict in the cache (observed or inherited) that is newer than the running build `buildSha`,
+ * looking at most REDEPLOY_WALK_MAX commits down from `tip`. A tip the cache has no verdict for
+ * is the target as is — the redeployer checks it. A tip whose cached red was observed in the
+ * redeployer's mirror worktree (mirrorWorktreePath of `wt`) falls back to the newest older green
+ * above the build. Any other red may be another worktree's environmental one, which the redeployer
+ * re-verifies; a build that is not a first-parent ancestor of `tip`, or no green, also leaves the
+ * tip the target, and the redeployer blocks that commit alone. The cache holds only full-check
+ * verdicts, so a cheaper command's green never makes a commit deployable.
+ * Never throws: a git failure leaves the tip as the target. */
+export async function redeployTarget(wt, tip, buildSha) {
+    const red = baselineCache.get(tip);
+    if (tip === "" || red?.status !== "red" || !(red.redFrom ?? []).includes(mirrorWorktreePath(wt)))
+        return tip;
+    const walk = gitLines(await gitTry(wt, "rev-list", "--first-parent", `--max-count=${REDEPLOY_WALK_MAX}`, tip));
+    const buildAt = walk.indexOf(buildSha);
+    if (buildAt === -1)
+        return tip;
+    for (const sha of walk.slice(0, buildAt)) {
+        if (baselineCache.get(sha)?.status === "green")
+            return sha;
+    }
+    return tip;
+}
 /** Verify main's own build/test suite at `wt`'s HEAD — which must be pristine main (the caller
- * is the fresh-tick path right after resetWorktreeToMain; a dirty or ahead worktree would
+ * is the fresh-run path right after resetWorktreeToMain; a dirty or ahead worktree would
  * measure the wrong thing). Cache hit returns immediately; on miss runs detectBuildCheck +
  * runBuildCheck once per SHA (in-flight deduped) and caches green/red. Never throws: git,
  * detection, and execution failures all resolve to "nothing blocks authoring". */
@@ -215,7 +281,7 @@ onRun,
  * circuits — see baselineCache). For the caller whose false block is expensive enough to pay
  * one extra run: the redeploy gate, where trusting another worktree's environmental red
  * strands the whole team on a stale build until main moves. A green from the re-run promotes
- * the SHA team-wide, which unblocks the role loops too. */
+ * the SHA team-wide, which unblocks the role runners too. */
 reverifyRed = false, 
 /** Ignore the cache entirely and run the suite here, even over a GREEN verdict. For the one
  * caller that cannot trust a green (BUGS.md 2026-10-06: the review gate re-attributing a
@@ -233,7 +299,9 @@ sampleSleep = sampleSleepClock,
  * doc edit main gained since its last observed green can break a test that reads the docs,
  * so only a real run may answer. A green from that run upgrades the SHA's verdict, and a red
  * replaces the inherited green for every consumer. */
-observedOnly = false) {
+observedOnly = false, 
+/** The check permit tier the run queues at; the main watch asks for the merge tier. */
+tier = CHECK_TIER.other) {
     const sha = await refSha(wt, "HEAD");
     if (!sha)
         return { baseline: null }; // No HEAD (unborn branch) — nothing to key on.
@@ -268,11 +336,11 @@ observedOnly = false) {
             // 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, CHECK_TIER.other, () => runWithCleanRetry(() => runBuildCheck(wt, check, undefined, undefined, sampleSleep), 
+            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 })));
+            (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:
@@ -296,6 +364,7 @@ observedOnly = false) {
                     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
@@ -337,7 +406,7 @@ export async function mainIsGreen(mirrorWt,
  * maxConcurrentChecks sizes the check permit this run takes. */
 config, 
 /** Hook for the build_check event — this run is a minute of the team's time and belongs in
- * the feed like the role loops' own baseline checks. */
+ * the feed like the role runners' own baseline checks. */
 onRun) {
     const check = await checkMainBaseline(mirrorWt, config, onRun, true);
     return check.baseline ? check.baseline.status === "green" : true;

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

@@ -0,0 +1,94 @@
+import { cachedBaselineVerdict, checkMainBaseline } from "./main-baseline.js";
+import { baselineCheckLogger } from "./main-red.js";
+import { CHECK_TIER } from "../concurrency/check-permit.js";
+import { gitTry } from "../git/git-run.js";
+import { treeDiffFiles } from "../git/git-diff.js";
+import { ensureDetachedWorktree } from "../git/worktree.js";
+import { gateMainWorktreePath } from "../paths.js";
+import { isExemptDiff } from "../review/exemptions.js";
+import { onlyQuarantined } from "../review/known-flakes.js";
+import { readEvents } from "../events/event-read.js";
+import { TUMWATER_SOURCE } from "../events/events.js";
+import { shortSha } from "../text/format.js";
+/** How many first-parent commits below the red tip the search for a last green looks at. */
+const CULPRIT_SEARCH_MAX = 50;
+/** How many recent events the owner lookup reads; an older `merged` event counts as none. */
+const OWNER_EVENT_TAIL = 2000;
+/** Name the first-parent commit that turned main red at `red.sha` (plans/fast-merge.md, Lever 2,
+ * part 4a). Runs inside the main watch's `_gate-main` checkout `wt`, re-pointing it per candidate
+ * and back at the tip before returning. Finds the newest first-parent commit with a cached green
+ * verdict, re-checks it fresh (a green that is red now means the environment broke, not a
+ * change), then bisects the commits since it — skipping doc-only ones — for the first red. A
+ * search that cannot name a commit says why instead of guessing. */
+export async function findRedCulprit(root, wt, config, red) {
+    const tip = red.sha;
+    const onRun = baselineCheckLogger(root, TUMWATER_SOURCE);
+    const mirror = gateMainWorktreePath(root);
+    const at = async (sha) => {
+        await ensureDetachedWorktree(root, mirror, sha);
+    };
+    const check = async (sha, reverifyRed, forceFresh, observedOnly) => {
+        await at(sha);
+        return (await checkMainBaseline(wt, config, onRun, reverifyRed, forceFresh, undefined, observedOnly, CHECK_TIER.merge))
+            .baseline;
+    };
+    try {
+        const walk = ((await gitTry(wt, "rev-list", "--first-parent", `--max-count=${CULPRIT_SEARCH_MAX + 1}`, tip)) ?? "")
+            .split("\n")
+            .filter((s) => s !== "")
+            .slice(1);
+        const green = walk.find((sha) => cachedBaselineVerdict(sha) === "green");
+        if (!green) {
+            return { kind: "unattributed", reason: `no green commit within ${CULPRIT_SEARCH_MAX} first-parent commits` };
+        }
+        const recheck = await check(green, false, true, false);
+        if (!recheck)
+            return { kind: "unattributed", reason: `the check made no verdict at ${shortSha(green)}` };
+        if (recheck.status === "red")
+            return { kind: "environment", green };
+        const exempt = config.review.exemptPaths;
+        const since = ((await gitTry(wt, "rev-list", "--first-parent", "--reverse", `${green}..${tip}`)) ?? "")
+            .split("\n")
+            .filter((s) => s !== "");
+        const candidates = [];
+        for (const sha of since) {
+            const files = await treeDiffFiles(wt, `${sha}^`, sha);
+            if (files === null || !isExemptDiff(files, exempt))
+                candidates.push(sha);
+        }
+        if (candidates.length === 0)
+            return { kind: "unattributed", reason: "no non-doc commit since the last green" };
+        // The last candidate is taken as red unrun: it is the tip, or only doc commits follow it.
+        let lo = 0;
+        let hi = candidates.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            const verdict = await check(candidates[mid], false, false, true);
+            if (!verdict)
+                return { kind: "unattributed", reason: `the check made no verdict at ${shortSha(candidates[mid])}` };
+            if (verdict.status === "red" && !onlyQuarantined(root, verdict.failingTests))
+                hi = mid;
+            else
+                lo = mid + 1;
+        }
+        const commit = candidates[lo];
+        const confirmed = await check(commit, true, false, true);
+        if (confirmed?.status !== "red" || onlyQuarantined(root, confirmed.failingTests)) {
+            return { kind: "unattributed", reason: `red did not reproduce at ${shortSha(commit)}` };
+        }
+        const failingTests = red.failingTests ?? []; // G was just verified green, so it carries none to subtract
+        const merged = readEvents(root, OWNER_EVENT_TAIL)
+            .reverse()
+            .find((ev) => ev.type === "merged" && ev.commit === commit);
+        return {
+            kind: "culprit",
+            commit,
+            ...(merged ? { runner: merged.source } : {}),
+            failingTests,
+            green,
+        };
+    }
+    finally {
+        await at(tip);
+    }
+}

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

@@ -0,0 +1,209 @@
+/** Post-merge machinery that can fail quietly while merges go on — surfaced as warnings so an
+ * operator or the selfcheck role sees them (plans/fast-merge.md "Guardrails"). Pure and
+ * synchronous over the event log and quarantine.json, so every surface (doctor's rows and the
+ * selfcheck digest) words them the same. Read-only: it never writes an event, state or file.
+ *
+ * G1 lives on the `main_check` / `main_red_hold` event trail (src/baseline/main-watch.ts,
+ * src/baseline/main-red.ts): only `main_check` events that actually ran the check
+ * (`durationMs` > 0; a cached or inherited verdict is ignored) and `main_red_hold` events
+ * count, and a `main_check` that passed (a red naming only quarantined tests is recorded
+ * passed) ends a red. G3 reads the quarantine list (src/review/known-flakes.ts) directly.
+ * 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 { shortSha } from "../text/format.js";
+import { squash } from "../text/text.js";
+/** How long a red main must last before the doctor and the selfcheck digest warn (G1). */
+export const RED_MAIN_WARN_MS = 30 * 60_000;
+/** True when the event is a `main_check` whose verdict actually ran the full check (G1's
+ * `relevant` rule): `durationMs` > 0, so a cached or inherited verdict (durationMs 0) is
+ * ignored. Shared by the report's main-red walk (src/report/report-main-red.ts) and
+ * `redMainWarning` below, so the two cannot disagree about whether a check ran. */
+function ranFullMainCheck(ev) {
+    return ev.type === "main_check" && typeof ev.durationMs === "number" && ev.durationMs > 0;
+}
+/** True when `ev` opens or extends a red spell on main (G1's rule): a `main_red_hold`, or a
+ * `main_check` that ran the full check and failed. The report's per-day main-red walk
+ * (src/report/report-main-red.ts) gates its spell opener on this, so it and G1 share the one
+ * rule for when main is red. */
+export function isRedMain(ev) {
+    return ev.type === "main_red_hold" || (ranFullMainCheck(ev) && ev.status === "failed");
+}
+/** True when `ev` is a `main_check` that ran the full check and passed — the event that ends a
+ * red spell (G1's rule: a red naming only quarantined tests is recorded passed). Shared with
+ * the report's main-red walk (src/report/report-main-red.ts), so a pass closes a spell the
+ * same way G1 ends its red. */
+export function isPassingMainCheck(ev) {
+    return ranFullMainCheck(ev) && ev.status === "passed";
+}
+/** A quarantined test's `firstSeen` age past which the doctor and digest warn it is being
+ * hidden (G3). */
+export const QUARANTINE_AGE_MS = 3 * DAY_MS;
+/** A quarantine list longer than this many tests warns on size (G3). */
+export const QUARANTINE_WARN_COUNT = 10;
+/** How many of the oldest quarantined tests a warning names before folding the rest into a
+ * remainder count. */
+const QUARANTINE_DETAIL_MAX = 3;
+/** G1 over `events`: warns when main has been red for more than RED_MAIN_WARN_MS, over the
+ * trailing 24 h of `events` from `now`. Only `main_check` events with `durationMs` > 0 and
+ * `main_red_hold` events count; a `main_check` with `durationMs` 0 (cached or inherited) is
+ * ignored; a pass (including one naming only quarantined tests, recorded passed) ends the red.
+ * The phrase names how long main has had no passing full check, the sha it has been red since,
+ * its clock time, and the newest red's first failing test when one is named. Returns null when
+ * main is green, or red for RED_MAIN_WARN_MS or less. */
+export function redMainWarning(events, now) {
+    const cutoff = now - DAY_MS;
+    const relevant = [];
+    for (const e of events) {
+        if (typeof e.ts !== "number" || e.ts < cutoff)
+            continue;
+        if (isRedMain(e) || isPassingMainCheck(e))
+            relevant.push(e);
+    }
+    if (relevant.length === 0)
+        return null;
+    let newest = relevant[0];
+    for (const e of relevant)
+        if (e.ts > newest.ts)
+            newest = e;
+    if (!isRedMain(newest))
+        return null;
+    const passes = relevant.filter(isPassingMainCheck);
+    const red = isRedMain;
+    const lastPass = passes.length > 0 ? passes[passes.length - 1] : undefined;
+    const reds = relevant.filter(red);
+    // No pass bounds the red spell, so the first red in the window opens it: a window with reds
+    // and no pass has been red for the whole window's coverage, so it reads "more than 24 h" (G1)
+    // no matter where the reds sit, not only when one happens to fall on the window's edge. A
+    // single fresh red (the only span recorded, e.g. a hold 47 min ago) reads its own age.
+    const firstRed = relevant.find((e) => red(e) && (lastPass === undefined || e.ts >= lastPass.ts));
+    // The red is "since" the event the duration is counted from, which for a red spell with more
+    // than one red is not the newest red: the design names the first red after the newest pass.
+    const startEv = firstRed ?? newest;
+    const durationMs = now - startEv.ts;
+    if (durationMs <= RED_MAIN_WARN_MS)
+        return null;
+    const unbroken = lastPass === undefined && reds.length > 1;
+    const duration = unbroken || durationMs >= DAY_MS ? "more than 24 h" : redDurationPhrase(durationMs);
+    const failing = Array.isArray(newest.failingTests) && typeof newest.failingTests[0] === "string" ? newest.failingTests[0] : undefined;
+    const head = `main has had no passing full check for ${duration}: red since ${shortSha(startEv.sha)} at ${clockHm(startEv.ts)}`;
+    return failing ? `${head} — ${squash(failing, 120)}` : head;
+}
+/** G3 over `entries` (the loadQuarantine list): warns when the list holds more than
+ * QUARANTINE_WARN_COUNT tests, or when any test's `firstSeen` is more than QUARANTINE_AGE_MS
+ * ago — an old entry is a failure the team has stopped seeing, and an unfiled one (`bug` empty)
+ * never leaves quarantine. The detail names the oldest tests with their age and BUGS.md heading
+ * (or "not filed"). Returns null when neither fires. */
+export function quarantineWarning(entries, now) {
+    const phrases = [];
+    if (entries.length > QUARANTINE_WARN_COUNT) {
+        phrases.push(`quarantine holds ${entries.length} tests — over the ${QUARANTINE_WARN_COUNT}-test ceiling`);
+    }
+    const old = entries
+        .filter((e) => e.firstSeen < now - QUARANTINE_AGE_MS)
+        .sort((a, b) => a.firstSeen - b.firstSeen);
+    if (old.length > 0) {
+        const named = old.slice(0, QUARANTINE_DETAIL_MAX).map((e) => {
+            const filed = e.bug ? squash(e.bug, 40) : "not filed";
+            return `"${squash(e.test, 40)}" (${filed}, ${humanAgo(e.firstSeen, now)})`;
+        });
+        const more = old.length > QUARANTINE_DETAIL_MAX ? ` (and ${old.length - QUARANTINE_DETAIL_MAX} more)` : "";
+        phrases.push(`quarantine holds ${old.length} test${old.length === 1 ? "" : "s"} over 3 days: ${named.join(", ")}${more}`);
+    }
+    return phrases.length > 0 ? phrases.join("; ") : null;
+}
+/** How many `main_revert` events in the trailing 24 h the doctor and digest warn once the
+ * daily ceiling is passed (G2's rate test): a burst of reverts reads like a flaky-revert
+ * habit, distinct from a single false revert. */
+export const REVERT_RATE_LIMIT = 5;
+/** One `main_revert` in the last 24 h looks false when either G2 test holds — its failure did
+ * not reproduce (a test it names has been quarantined at or since the revert, or a later
+ * `main_check`'s `quarantined` list names it), or its change came back unchanged and main
+ * stayed green (a later `merged` event carries the culprit's patch-id, and the first
+ * `main_check` after that merge which actually ran the check passed). */
+function revertLooksFalse(r, events, quarantine) {
+    const rts = typeof r.ts === "number" ? r.ts : 0;
+    const tests = Array.isArray(r.failingTests)
+        ? r.failingTests.filter((t) => typeof t === "string")
+        : [];
+    const firstTest = tests[0];
+    // Did not reproduce: the named test is quarantined at or since the revert, or a later
+    // main_check's `quarantined` list names it (src/baseline/main-watch.ts records a red naming
+    // only quarantined flaky tests as passed there).
+    if (firstTest !== undefined &&
+        (quarantine.some((q) => q.test === firstTest && q.lastSeen >= rts) ||
+            events.some((e) => e.type === "main_check" &&
+                typeof e.ts === "number" &&
+                e.ts >= rts &&
+                Array.isArray(e.quarantined) &&
+                e.quarantined.includes(firstTest))))
+        return "quarantined";
+    // Came back unchanged and main stayed green: a later `merged` carries this revert's
+    // patch-id, and the first `main_check` after that merge which ran the check passed.
+    const patch = typeof r.patchId === "string" ? r.patchId : undefined;
+    if (patch === undefined)
+        return null;
+    const remerged = events.find((e) => e.type === "merged" && e.patchId === patch && typeof e.ts === "number" && e.ts >= rts);
+    if (remerged === undefined)
+        return null;
+    const rmTs = typeof remerged.ts === "number" ? remerged.ts : 0;
+    const after = events
+        .filter((e) => e.type === "main_check" &&
+        typeof e.ts === "number" &&
+        e.ts >= rmTs &&
+        typeof e.durationMs === "number" &&
+        e.durationMs > 0)
+        .sort((a, b) => a.ts - b.ts)[0];
+    return after?.status === "passed" ? "remerged" : null;
+}
+/** G2 over `events` and the quarantine list: warns on a `main_revert` in the trailing 24 h that
+ * looks false, and on more than REVERT_RATE_LIMIT reverts a day. The detail names each
+ * false-looking revert (culprit sha and which test failed / that it landed again unchanged)
+ * and the count when over the rate limit. Returns the phrases that fire (empty when none do). */
+export function revertWarnings(events, quarantine, now) {
+    const cutoff = now - DAY_MS;
+    const reverts = events.filter((e) => e.type === "main_revert" && typeof e.ts === "number" && e.ts >= cutoff);
+    if (reverts.length === 0)
+        return [];
+    const phrases = [];
+    if (reverts.length > REVERT_RATE_LIMIT) {
+        phrases.push(`${reverts.length} reverts in the last 24 h — over the ${REVERT_RATE_LIMIT}-revert ceiling`);
+    }
+    for (const r of reverts) {
+        const culprit = typeof r.commit === "string" ? r.commit : typeof r.sha === "string" ? r.sha : "";
+        const reason = revertLooksFalse(r, events, quarantine);
+        if (reason === "quarantined") {
+            const tests = Array.isArray(r.failingTests)
+                ? r.failingTests.filter((t) => typeof t === "string")
+                : [];
+            phrases.push(`revert ${shortSha(culprit)} blamed ${squash(tests[0] ?? "", 60)}, which has been quarantined since — the failure did not reproduce`);
+        }
+        else if (reason === "remerged") {
+            phrases.push(`revert ${shortSha(culprit)}'s change merged again unchanged and main stayed green — the revert looks false`);
+        }
+    }
+    return phrases;
+}
+/** Both guardrail phrases that fire for `root`, reading the trailing 24 h of the event log and
+ * quarantine.json, oldest-test text bounded as the doctor rows are. */
+export function guardrailWarnings(root, now = Date.now()) {
+    const warnings = [];
+    const events = readEventsSince(root, DAY_MS).events;
+    const red = redMainWarning(events, now);
+    if (red !== null)
+        warnings.push(red);
+    const q = loadQuarantine(root);
+    const qw = quarantineWarning(q, now);
+    if (qw !== null)
+        warnings.push(qw);
+    warnings.push(...revertWarnings(events, q, now));
+    return warnings;
+}
+/** "40 min", "3 h" — the duration a red main's warning names. */
+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`;
+}