tumwater 0.2.0 → 0.3.0

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

@@ -1,34 +1,50 @@
-// vocabulary: plain
-import { baselineBlocked } from "../roles/roles.js";
+import { baselineBlocked, BUGFIX_ROLE } from "../roles/roles.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { enqueueRolePrompt } from "../inbox/inbox.js";
 import { isCustomRole, liveConfig } from "../config/config.js";
-import { BUILD_CHECK_TIMEOUT_MS } from "../build/build-check-detect.js";
-import { failureHeadline } from "../build/build-check-report.js";
+import { BUILD_CHECK_TIMEOUT_MS, mergeCommandOf } from "../build/build-check-detect.js";
+import { failureHeadline, FAILING_TESTS_MAX } from "../build/build-check-report.js";
 import { baselineCheckEventLogger, buildCheckSkipWarning, sleptPhrase } from "../build/build-check-events.js";
-import { checkMainBaseline } from "./main-baseline.js";
-import { buildMainRedNote } from "../prompt/gate-prompts.js";
+import { checkMainBaseline, watchedBaseline } from "./main-baseline.js";
+import { buildMainRedNote } from "../prompt/gate-notes.js";
 import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
-import { mainRedPhrase } from "../text/phrases.js";
+import { mainRedPhrase, plural } from "../text/phrases.js";
+import { clipToWidth } from "../text/text-width.js";
+import { shortSha } from "../text/format.js";
 import { branchHead } from "../git/git.js";
 import { gateMainWorktreePath } from "../paths.js";
 import { useWorktree } from "../git/worktree-use.js";
 import { ensureDetachedWorktree } from "../git/worktree.js";
-/** Red-main baseline gate for fresh authoring ticks: before an
+/** Red-main baseline gate for fresh authoring runs: before an
  * authoring run is spent on top of pristine main, verify that MAIN ITSELF is green — a red main
  * rejects every code diff deterministically at the review gate (BUGS.md's "Build broken on main"
  * and "Tests red on main" entries), so while a SHA is known red the blocked roles skip authoring
- * instead of burning runs that are guaranteed to fail. Split out of loop.ts — which keeps the
- * tick lifecycle around it — because this is a self-contained policy with its own per-process
- * state (one harness-level `main_red_hold` event per newly-discovered red SHA) and its own
- * event contract; what it borrows from the loop is identity and the role's worktree, and it
+ * instead of burning runs that are guaranteed to fail. Split out of runner.ts — which keeps the
+ * run lifecycle around it — because this is a self-contained policy with its own per-process
+ * state (one harness-level `main_red_hold` event AND one queued healer prompt per
+ * newly-discovered red SHA) and its own
+ * event contract; what it borrows from the role is identity and the role's worktree, and it
  * consumes
  * build/build-check.ts's checkMainBaseline machinery (detection + execution + per-SHA cache),
- * which stays unaware of ticks. */
+ * which stays unaware of runs. */
 /** The last main SHA for which this process logged a red-main hold event (the baseline check): one
- * harness-level warning per newly-discovered red SHA, not one per blocked role's tick —
+ * harness-level warning per newly-discovered red SHA, not one per blocked role's run —
  * module-level so every runner in the team shares it. A restart re-logs once: the cache is cold
  * then too, and an operator restarting into a still-red main should see why nothing merges. */
 let lastMainRedSha = null;
+/** The key of the last failing set the healer was sent a prompt for: the sorted failing test
+ * names, or the red SHA when the red names none. Two red commits with the same failing set send
+ * one heal prompt, not one per commit; a green main observed by the gate or the bugfix handoff
+ * clears it, so a set that returns after green is healed again. */
+let lastHealKey = null;
+/** The failing tests a red verdict names, when the list is complete — non-empty and short of
+ * FAILING_TESTS_MAX, which may have been cut short (the same rule as onlyKnownMainFailures).
+ * Empty when it names none: main's red is then not a set of known failures, and the block stays. */
+function namedFailures(red) {
+    const tests = red.failingTests ?? [];
+    return tests.length > 0 && tests.length < FAILING_TESTS_MAX ? tests : [];
+}
 /** The red-main message's shared spine — the SHA, script, and failure headline a red baseline
  * carries, phrased once so the once-per-SHA warning and the main_red outcome cannot drift apart
  * over what main looks like. `action` is the consequence each caller names. */
@@ -37,19 +53,74 @@ function redMainMessage(red, action) {
     return `${mainRedPhrase(red.sha)} (${red.script}${firstLine ? `: ${firstLine}` : ""}) — ${action}`;
 }
 /** Log the team-wide `main_red_hold` event (the notify hook pages it) for `red`'s SHA at
- * most once per process. Module-level (with lastMainRedSha) so the gate and the bugfix
- * handoff share one guard: whichever observes the red first logs it, the other stays silent. */
-function warnMainRedOnce(root, red) {
+ * most once per process, and hand the red suite to the healer. Module-level (with
+ * lastMainRedSha) so the gate and the bugfix handoff share one guard: whichever observes the
+ * red first logs it, the other stays silent. `foundBy` is the role whose path verified the
+ * red — when that role is not bugfix itself, one prompt is enqueued to bugfix's own inbox so
+ * the healer runs on the orchestrator's next poll instead of waiting out its own interval or
+ * deferral; bugfix finding its own red skips the enqueue because its running run already
+ * carries the note and IS the heal (and enqueuing from inside it would queue a second run). A
+ * queued per-role prompt makes the role due by itself (`isEligible`, scheduling.ts, returns
+ * `{ run: true, reason: "inbox" }` on a non-empty inbox before any interval, backoff, or
+ * deferral check), and `pollRunnerReasons` skips the need-based deferral block for reason
+ * `inbox`, so no scheduler change is needed. A heal prompt that cannot be queued is warned under
+ * `foundBy` and clears the heal key, never thrown. */
+function warnMainRedOnce(root, red, foundBy) {
     if (lastMainRedSha === red.sha)
         return;
     lastMainRedSha = red.sha;
+    const named = namedFailures(red);
     logEventBestEffort(root, {
         source: TUMWATER_SOURCE,
         type: "main_red_hold",
         sha: red.sha,
         script: red.script,
-        message: redMainMessage(red, "code merges blocked until main is green"),
+        ...(named.length > 0 ? { failingTests: named } : {}),
+        message: named.length > 0
+            ? `${mainRedPhrase(red.sha)} (${plural(named.length, "failing test")}: ${clipToWidth(named[0] ?? "", 80)}${named.length > 1 ? `, +${named.length - 1} more` : ""}); changes that add no new failures still merge`
+            : redMainMessage(red, "code merges blocked until main is green"),
     });
+    // Bugfix is the only repairer, and it is exempt from mainRedGate — but it is a work role
+    // that with no open bugs defers like a maintenance role, so a red main discovered by any
+    // other path could sit unrepaired until bugfix's own interval or a coincidental wake.
+    // Queue the heal: one prompt per newly-verified red SHA per process (a restart re-queues
+    // once, desirable because the cache is cold then too). With named failures the key is the
+    // failing set, so a second red commit with the same failures queues nothing.
+    const healKey = named.length > 0 ? [...named].sort().join("\n") : red.sha;
+    if (lastHealKey === healKey)
+        return;
+    lastHealKey = healKey;
+    if (baseRoleOf(foundBy) !== BUGFIX_ROLE) {
+        try {
+            enqueueRolePrompt(root, BUGFIX_ROLE, mainRedHealPrompt(red.sha));
+        }
+        catch (err) {
+            // Clear the key so a later verification retries the heal. lastMainRedSha stays set, so a
+            // second call for this same SHA still returns early: the retry comes with the next red
+            // SHA or a fresh process.
+            lastHealKey = null;
+            warnEventBestEffort(root, foundBy, `could not queue the heal prompt for bugfix: ${errorMessage(err)}`);
+        }
+    }
+}
+/** The one-line, self-limiting directive queued for the bugfix healer when a non-bugfix path
+ * newly verifies a red main. It names the short SHA the check was reported red at, tells the
+ * healer to verify main is green now, and to reproduce and land the fix only if it is still
+ * red. The self-limiting wording is the green race's whole handling: if main turned green
+ * before the healer consumes the prompt, bugfixMainRedNote returns undefined (no `<main-red>`
+ * note is appended) and the "verify green" clause makes the run a no-op. */
+export function mainRedHealPrompt(sha, detail) {
+    const base = `Main was reported red at commit ${shortSha(sha)}. Verify main is green now; if it is still red, reproduce the failure and land the fix.`;
+    if (!detail)
+        return base;
+    const tests = detail.failingTests.length > 0 ? ` Failing: ${detail.failingTests.join("; ")}.` : "";
+    const tail = detail.outputTail && detail.outputTail.length > 0 ? ` Output tail: ${detail.outputTail.join(" | ")}` : "";
+    return `${base} The watch named ${shortSha(detail.culprit)} as the commit that turned it red.${tests}${tail}`;
+}
+/** Queue the heal prompt for bugfix with the culprit's detail: the fallback when the automatic
+ * revert (src/baseline/main-revert.ts) is skipped or fails. */
+export function queueCulpritHeal(root, tip, detail) {
+    enqueueRolePrompt(root, BUGFIX_ROLE, mainRedHealPrompt(tip, detail));
 }
 /** checkMainBaseline's per-run hook: log the one run per SHA (cache misses only) under the role
  * that paid for it, with its duration — the gate's build_check sibling, so both halves of the
@@ -57,7 +128,7 @@ function warnMainRedOnce(root, red) {
  * check this module runs — the bugfix handoff, the authoring gate, and mainTipVerdict's tip
  * check (which review.ts's gate and merge-check-failures.ts's attributeRedCheck reach
  * through it) — so the event's shape cannot drift between them. */
-function baselineCheckLogger(root, role) {
+export function baselineCheckLogger(root, role) {
     return baselineCheckEventLogger(role, (event) => logEventBestEffort(root, event));
 }
 /** Red-main handoff for the `bugfix` healer: mainRedGate exempts
@@ -66,19 +137,23 @@ function baselineCheckLogger(root, role) {
  * (cache and provisional-red re-verification reused unchanged, so it costs at most the one run
  * the gate would have paid for) and, when main is red, returns the note that points the healer
  * at the failure. Returns undefined on green, no declared check, or an environmental skip — the
- * healer's tick then proceeds exactly as it did before this existed. Never throws. */
+ * healer's run then proceeds exactly as it did before this existed. Never throws. */
 export async function bugfixMainRedNote(root, role, wt) {
     // The declared check is detected through the live config (plans/portability.md §6/7); a
-    // broken file degrades to defaults, which declare none — the tick then proceeds as before.
+    // broken file degrades to defaults, which declare none — the run then proceeds as before.
     const config = liveConfig(root);
-    const baseline = await checkMainBaseline(wt, config, baselineCheckLogger(root, role));
+    const baseline = mergeCommandOf(config)
+        ? { baseline: await watchedBaseline(wt) }
+        : await checkMainBaseline(wt, config, baselineCheckLogger(root, role));
     const red = baseline.baseline;
+    if (red?.status === "green")
+        lastHealKey = null;
     if (red?.status !== "red")
         return undefined;
-    warnMainRedOnce(root, red);
+    warnMainRedOnce(root, red, role);
     return buildMainRedNote(red.sha, red.script, failureHeadline(red.outputTail), red.outputTail);
 }
-/** Gate one fresh tick on main's baseline. Returns null when authoring may proceed — role not
+/** Gate one fresh run on main's baseline. Returns null when authoring may proceed — role not
  * blocked, no declared check, green, or an environmental skip (warned under the role and
  * proceeded with, exactly like the review gate's pre-check) — otherwise the terminal
  * `main_red` outcome for the caller to return as-is. Never throws: git, detection, and
@@ -86,8 +161,11 @@ export async function bugfixMainRedNote(root, role, wt) {
 export async function mainRedGate(root, role, wt, 
 /** The sleep clock the baseline run measures host suspension with; defaults to the real
  * sampleSleepClock. A test seam — production callers leave it unset. */
-sampleSleep) {
-    // User-defined loops are blocked alongside the built-in code roles (plans/user-defined-loops.md):
+sampleSleep, 
+/** Called with main's failing tests when the red names them: the role then runs on the red
+ * main instead of ending `main_red`, and the caller puts them in its prompt. */
+onKnownRed) {
+    // User-defined roles are blocked alongside the built-in code roles (plans/user-defined-loops.md):
     // an unknown charter may produce code, and on red main such diffs are rejected deterministically
     // at the gate's pre-check — an authoring run would be pure waste. Customs come from
     // tumwater.json, not the catalog, so read the live config (stat-cached; a broken file
@@ -95,7 +173,12 @@ sampleSleep) {
     const cfg = liveConfig(root);
     if (!baselineBlocked(role) && !isCustomRole(cfg, role))
         return null;
-    const baseline = await checkMainBaseline(wt, cfg, baselineCheckLogger(root, role), false, false, sampleSleep);
+    // With check.mergeCommand set the lock no longer runs the full check, and neither does this
+    // gate: it reads the main watch's newest verdict for main's tip (or its nearest checked
+    // ancestor). No verdict yet reads as green.
+    const baseline = mergeCommandOf(cfg)
+        ? { baseline: await watchedBaseline(wt) }
+        : await checkMainBaseline(wt, cfg, baselineCheckLogger(root, role), false, false, sampleSleep);
     if (baseline.unverified) {
         // The baseline run spanned a host sleep: no verdict about main, nothing cached (BUGS.md
         // 2026-09-30). Warn-and-proceed, like a skip — the sleep is named, not a test failure.
@@ -108,17 +191,24 @@ sampleSleep) {
     }
     if (baseline.baseline?.status === "red") {
         const red = baseline.baseline;
-        warnMainRedOnce(root, red);
+        warnMainRedOnce(root, red, role);
+        const named = namedFailures(red);
+        if (named.length > 0) {
+            onKnownRed?.(named);
+            return null;
+        }
         return {
             result: "main_red",
             summary: "code merges blocked until main is green",
-            // The cause rides the outcome so the tick's `run_end` carries it
-            // (tick-finalize.ts folds it into state.lastError before logging): the digest itemizes
+            // The cause rides the outcome so the run's `run_end` carries it
+            // (run-finalize.ts folds it into state.lastError before logging): the digest itemizes
             // the outcome that blocks every merge, instead of leaving it a bare count behind a
             // once-per-SHA warning (BUGS.md 2026-09-28).
             error: redMainMessage(red, "authoring skipped until main is green"),
         };
     }
+    if (baseline.baseline?.status === "green")
+        lastHealKey = null;
     return null;
 }
 /** Serializes mainTipVerdict's use of its one worktree: the merge pipeline's verifies run their
@@ -141,10 +231,27 @@ let gateMainQueue = Promise.resolve();
  * failure on a clock- or load-sensitive test whose cached green has gone stale (BUGS.md
  * 2026-10-06). The merge pipeline's attribution reads the cached verdict instead. */
 export function mainTipVerdict(root, role, mainBranch, config, forceFresh = false) {
-    const run = gateMainQueue.then(() => verdictAtMainTip(root, role, mainBranch, config, forceFresh));
+    return queueBehindMainGates(() => verdictAtMainTip(root, role, mainBranch, config, forceFresh));
+}
+/** Run `task` after every earlier gate-main task has settled, and make it the queue's new tail. A
+ * task's rejection reaches only its own caller; the next task still runs. */
+function queueBehindMainGates(task) {
+    const run = gateMainQueue.then(task);
     gateMainQueue = run.catch(() => undefined);
     return run;
 }
+/** Run `fn` in the `_gate-main` mirror re-pointed at `mainBranch`'s tip, queued behind the gates
+ * mainTipVerdict serves (gateMainQueue) and holding the mirror as they do. The main watch's way in
+ * (main-watch.ts): it hands `fn` the checkout and the tip it holds. Rejects when main is
+ * unreadable or the checkout fails — the caller is a background task that must catch. */
+export function withMainTipWorktree(root, mainBranch, fn) {
+    return queueBehindMainGates(() => useWorktree(root, gateMainWorktreePath(root), async () => {
+        const tip = await branchHead(root, mainBranch);
+        if (!tip)
+            throw new Error(`${mainBranch} is unreadable`);
+        return fn(await ensureDetachedWorktree(root, gateMainWorktreePath(root), tip));
+    }));
+}
 async function verdictAtMainTip(root, role, mainBranch, config, forceFresh) {
     // Hold the `_gate-main` mirror from before ensureDetachedWorktree (its reset is part of the
     // use) through the baseline check (plans/disk-floor.md, part 2/4).
@@ -164,7 +271,7 @@ async function verdictAtMainTipIn(root, role, mainBranch, config, forceFresh) {
         if (baseline?.status === "green")
             return { status: "green", sha: baseline.sha };
         if (baseline?.status === "red") {
-            warnMainRedOnce(root, baseline);
+            warnMainRedOnce(root, baseline, role);
             return { status: "red", sha: baseline.sha };
         }
         return {

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

@@ -0,0 +1,133 @@
+import { queueCulpritHeal } from "./main-red.js";
+import { gateCommandOf } from "../build/build-check-detect.js";
+import { runScopedBuildCheck } from "../build/build-check-scoped.js";
+import { withLock } from "../concurrency/lock.js";
+import { logEventBestEffort, TUMWATER_SOURCE, warnEventBestEffort } from "../events/events.js";
+import { branchHead, patchId } from "../git/git.js";
+import { gitTry } from "../git/git-run.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { ensureDetachedWorktree } from "../git/worktree.js";
+import { useWorktree } from "../git/worktree-use.js";
+import { ffMainToOrWhy } from "../merge/merge-git.js";
+import { revertCommitIn } from "../operator/revert.js";
+import { mergeLockDir, mergeWorktreePath } from "../paths.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { errorMessage } from "../text/text.js";
+import { shortSha } from "../text/format.js";
+const REVERT_PREFIXES = ["tumwater(operator): Revert", "tumwater(tumwater): Revert"]; // vocabulary-ok: commit prefixes are machine strings
+/** Why the culprit is not reverted automatically, or null when it should be: no runner (an
+ * operator or hand commit), a director's merge, a revert itself, or a commit whose revert
+ * already merged. */
+export async function revertSkipReason(root, mainBranch, c) {
+    if (c.runner === undefined)
+        return "no role runner merged it";
+    if (baseRoleOf(c.runner) === DIRECTOR_ROLE)
+        return "the director merged it";
+    const subject = ((await gitTry(root, "log", "-1", "--format=%s", c.commit)) ?? "").trim();
+    if (REVERT_PREFIXES.some((p) => subject.startsWith(p)))
+        return "it is itself a revert";
+    const merged = (await gitTry(root, "log", mainBranch, "--format=%s", "--fixed-strings", `--grep=Revert ${shortSha(c.commit)}`)) ?? "";
+    if (merged.split("\n").some((s) => REVERT_PREFIXES.some((p) => s === `${p} ${shortSha(c.commit)}`)))
+        return "a revert of it already merged";
+    return null;
+}
+/** The main watch's culprit hand-off: starts the automatic revert, or falls back to bugfix's heal
+ * prompt when the revert is skipped. Never rejects, because its caller discards the promise and an
+ * unhandled rejection would end the orchestrator: a heal prompt that cannot be queued is warned. */
+export async function routeMainCulprit(root, mainBranch, c, startRevert) {
+    const skip = await revertSkipReason(root, mainBranch, c);
+    if (skip === null) {
+        startRevert(c);
+        return;
+    }
+    try {
+        queueCulpritHeal(root, c.tip, { culprit: c.commit, failingTests: c.failingTests });
+    }
+    catch (err) {
+        warnEventBestEffort(root, TUMWATER_SOURCE, `not reverting ${shortSha(c.commit)} (${skip}) and could not queue the heal prompt for bugfix: ${errorMessage(err)}`);
+    }
+}
+/** Run one revert task on main's current tip in the shared `_merge` checkout: revert the culprit,
+ * run `check.gateCommand` on the result when one is set (red aborts), and fast-forward main under
+ * the merge lock. Logs `main_revert` on success and calls `onReverted` (the hand-back to a role);
+ * every failure queues the heal prompt instead. Never throws: a hand-off that cannot be queued is
+ * warned, not thrown. */
+export async function runMainRevert(root, mainBranch, config, c, onReverted, onFailed) {
+    /** Hand the failure to a role and return the warning's suffix saying truthfully what happened. */
+    const heal = (reason, outputTail) => {
+        const toReviewer = c.postReview && onFailed;
+        try {
+            if (toReviewer)
+                onFailed(c, reason);
+            else
+                queueCulpritHeal(root, c.tip, { culprit: c.commit, failingTests: c.failingTests, outputTail });
+            return toReviewer ? "sent the reviewer's reasons to its role" : "queued the heal prompt for bugfix";
+        }
+        catch (err) {
+            return toReviewer
+                ? `could not send the reviewer's reasons to its role: ${errorMessage(err)}`
+                : `could not queue the heal prompt for bugfix: ${errorMessage(err)}`;
+        }
+    };
+    try {
+        const failure = await useWorktree(root, mergeWorktreePath(root), async () => {
+            const tip = await branchHead(root, mainBranch);
+            if (tip === null)
+                return { reason: `${mainBranch} is unreadable` };
+            const wt = await ensureDetachedWorktree(root, mergeWorktreePath(root), tip);
+            const subject = ((await gitTry(wt, "log", "-1", "--format=%s", c.commit)) ?? "").trim();
+            const tests = c.failingTests.length > 0 ? `\n\nFailing tests: ${c.failingTests.join("; ")}` : "";
+            const why = c.postReview
+                ? `which a post-merge review rejected.\n\nReasons: ${c.postReview.reasons.join("; ")}`
+                : `which turned main red.${tests}`;
+            const message = `${stampedSubject("tumwater", `Revert ${shortSha(c.commit)}`)}\n\nReverts ${c.commit} (${subject}), ${why}`;
+            const reverted = await revertCommitIn(wt, c.commit, message);
+            if (!reverted.ok)
+                return { reason: reverted.error };
+            if (gateCommandOf(config) !== undefined) {
+                const gate = await runScopedBuildCheck(root, TUMWATER_SOURCE, "gate", wt, config);
+                if (gate && gate.outcome.status !== "passed")
+                    return { reason: `the gate command was ${gate.outcome.status} on the revert`, tail: gate.outcome.outputTail };
+            }
+            const ffFailure = await withLock(mergeLockDir(root), () => ffMainToOrWhy(root, reverted.sha, mainBranch));
+            if (ffFailure !== null)
+                return { reason: ffFailure };
+            // The culprit's patch-id (`C^...C`, src/git/git.ts patchId, -U0 so a re-landing onto a
+            // moved main keeps the id): the fast-merge guardrail G2 matches a later `merged`
+            // event against it to spot a change that came back unchanged (plans/fast-merge.md).
+            const culpritPatch = await patchId(wt, `${c.commit}^`, c.commit).catch(() => null);
+            logEventBestEffort(root, {
+                source: TUMWATER_SOURCE,
+                type: "main_revert",
+                commit: c.commit,
+                revert: reverted.sha,
+                runner: c.runner,
+                failingTests: c.failingTests,
+                ...(culpritPatch ? { patchId: culpritPatch } : {}),
+            });
+            await onReverted?.(c).catch((err) => logEventBestEffort(root, {
+                source: TUMWATER_SOURCE,
+                type: "warning",
+                message: `could not hand ${shortSha(c.commit)} back to its role: ${errorMessage(err)}`,
+            }));
+            return null;
+        });
+        if (failure !== null) {
+            const suffix = heal(failure.reason, failure.tail);
+            logEventBestEffort(root, {
+                source: TUMWATER_SOURCE,
+                type: "warning",
+                message: `could not revert ${shortSha(c.commit)}: ${failure.reason} — ${suffix}`,
+            });
+        }
+    }
+    catch (err) {
+        const suffix = heal(errorMessage(err));
+        logEventBestEffort(root, {
+            source: TUMWATER_SOURCE,
+            type: "warning",
+            message: `revert of ${shortSha(c.commit)} failed: ${errorMessage(err)} — ${suffix}`,
+        });
+    }
+}

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

@@ -0,0 +1,184 @@
+import { checkMainBaseline } from "./main-baseline.js";
+import { findRedCulprit } from "./main-culprit.js";
+import { baselineCheckLogger, withMainTipWorktree } from "./main-red.js";
+import { CHECK_TIER } from "../concurrency/check-permit.js";
+import { FAILING_TESTS_MAX } from "../build/build-check-report.js";
+import { detectBuildCheck } from "../build/build-check-detect.js";
+import { gitTry } from "../git/git-run.js";
+import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { errorMessage } from "../text/text.js";
+import { fileQuarantineBugsOnMain } from "../backlog/backlog-archive.js";
+import { loadQuarantine, markQuarantineFiled, onlyQuarantined, quarantinedTests, quarantineTests, releaseQuarantine, } from "../review/known-flakes.js";
+import { shortSha } from "../text/format.js";
+/** 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
+ * nearest tip it checked while the newest head waits — and every quarantined flaky test
+ * (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)])];
+}
+/** 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
+ * FAILING_TESTS_MAX may have been cut short, so it never counts as complete. */
+export function onlyKnownMainFailures(root, failingTests) {
+    if (!failingTests || failingTests.length === 0 || failingTests.length >= FAILING_TESTS_MAX)
+        return null;
+    const known = new Set(knownMainFailures(root));
+    return failingTests.every((t) => known.has(t)) ? [...failingTests] : null;
+}
+export function createMainWatch(root, mainBranch, onCulprit) {
+    let lastWatched;
+    let inFlight = null;
+    let housekeeping = null;
+    let lastFilingWarning = "";
+    /** Release quarantined tests whose bug left `## Open`, and file the bugs of newly quarantined
+     * ones on main. A filing the primary checkout cannot take warns (once per reason) and is
+     * retried on a later poll. Never throws. */
+    async function settleQuarantine() {
+        try {
+            const released = releaseQuarantine(root);
+            if (released.length > 0) {
+                logEventBestEffort(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "warning",
+                    message: `quarantine released ${released.join(", ")}: its BUGS.md entry is no longer open`,
+                });
+            }
+            const pending = loadQuarantine(root).filter((e) => e.bug === "");
+            if (pending.length === 0)
+                return;
+            const outcome = await fileQuarantineBugsOnMain(root, pending);
+            if (outcome.status === "filed") {
+                markQuarantineFiled(root, outcome.bugs);
+                lastFilingWarning = "";
+                return;
+            }
+            if (outcome.reason !== lastFilingWarning) {
+                lastFilingWarning = outcome.reason;
+                logEventBestEffort(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "warning",
+                    message: `quarantined flaky tests are not filed in BUGS.md yet: ${outcome.reason}`,
+                });
+            }
+        }
+        catch (err) {
+            logEventBestEffort(root, {
+                source: TUMWATER_SOURCE,
+                type: "warning",
+                message: `quarantine housekeeping failed: ${errorMessage(err)}`,
+            });
+        }
+    }
+    async function watchOnce(mainHead, config) {
+        if (!detectBuildCheck(root, config)) {
+            lastWatched = mainHead; // no declared check: nothing to watch until main moves
+            return;
+        }
+        await withMainTipWorktree(root, mainBranch, async (wt) => {
+            const started = Date.now();
+            let ran = false;
+            const onRun = baselineCheckLogger(root, TUMWATER_SOURCE);
+            const hook = (run) => {
+                ran = true;
+                onRun(run);
+            };
+            let check = await checkMainBaseline(wt, config, hook, false, false, undefined, false, CHECK_TIER.merge);
+            if (check.baseline?.status === "red") {
+                const first = check.baseline;
+                check = await checkMainBaseline(wt, config, hook, true, false, undefined, false, CHECK_TIER.merge);
+                // A red the same tree's confirming re-run turns green is a flake: quarantine its tests.
+                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.
+            if (!baseline)
+                return void (lastWatched = await headOf(wt));
+            lastWatched = baseline.sha;
+            // A red naming only quarantined tests counts as green: no bisect, 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 } : {}),
+            });
+            if (!red)
+                return;
+            // Once per red head: lastWatched already holds it, so a later poll does not search again.
+            const found = await findRedCulprit(root, wt, config, baseline);
+            if (found.kind === "culprit") {
+                logEventBestEffort(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "main_culprit",
+                    commit: found.commit,
+                    ...(found.runner !== undefined ? { runner: found.runner } : {}),
+                    failingTests: found.failingTests,
+                    green: found.green,
+                });
+                onCulprit?.({
+                    commit: found.commit,
+                    ...(found.runner !== undefined ? { runner: found.runner } : {}),
+                    failingTests: found.failingTests,
+                    tip: baseline.sha,
+                });
+            }
+            else {
+                logEventBestEffort(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "warning",
+                    message: found.kind === "environment"
+                        ? `main's last green commit ${shortSha(found.green)} is red now too — not attributing`
+                        : `main watch could not name the commit that turned main red: ${found.reason}`,
+                });
+            }
+        });
+    }
+    return {
+        poll(mainHead, held, config) {
+            if (!held && !housekeeping) {
+                housekeeping = settleQuarantine().finally(() => {
+                    housekeeping = null;
+                });
+            }
+            if (held || mainHead === "" || inFlight || mainHead === lastWatched)
+                return;
+            inFlight = watchOnce(mainHead, config)
+                .catch((err) => {
+                // A failed watch (main unreadable, checkout refused) records nothing and is not
+                // retried until main moves, so a persistent failure warns once per head.
+                lastWatched = mainHead;
+                logEventBestEffort(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "warning",
+                    message: `main watch could not check main: ${errorMessage(err)}`,
+                });
+            })
+                .finally(() => {
+                inFlight = null;
+            });
+        },
+        idle: async () => {
+            while (inFlight || housekeeping)
+                await (inFlight ?? housekeeping);
+        },
+    };
+}
+async function headOf(wt) {
+    return ((await gitTry(wt, "rev-parse", "HEAD")) ?? "").trim();
+}

package/dist/src/brief/brief-edit.js

@@ -1,34 +1,32 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
-import { INITIAL_PROMPT_MAX_CHARS, PROMPT_END, PROMPT_START, briefPath, replaceInitialPrompt } from "./brief.js";
+import { BRIEF_TEXT_MAX_CHARS, PROMPT_END, PROMPT_START, briefPath, replaceBriefText } from "./brief.js";
 import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
-import { withStateLock } from "../concurrency/lock.js";
+import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
 import { writeTextAtomic } from "../files/files.js";
 import { stampedSubject } from "../git/commit-message.js";
-import { primaryWorktreeLockPath } from "../paths.js";
 import { PREFILL_REASON } from "../text/phrases.js";
 import { tooLongMessage } from "../text/text.js";
 const NO_BRIEF = "no project brief with a prompt block found — run `tumwater init` first";
-/** Replace the initial prompt with `text` under the checks init applies (non-empty, at most
- * INITIAL_PROMPT_MAX_CHARS, no prompt marker), write it under the primary-worktree lock, and
+/** Replace the brief text with `text` under the checks init applies (non-empty, at most
+ * BRIEF_TEXT_MAX_CHARS, no prompt marker), write it under the primary-worktree lock, and
  * commit that one file on main. The one writer behind `tumwater brief --file` and the
  * dashboard's Settings card, so the two cannot drift. */
-export async function editInitialPrompt(root, text) {
+export async function editBriefText(root, text) {
     const prompt = text.trim();
     if (prompt === "")
         return { ok: false, error: "the new brief is empty" };
-    if (prompt.length > INITIAL_PROMPT_MAX_CHARS)
-        return { ok: false, error: tooLongMessage("the new brief", prompt.length, INITIAL_PROMPT_MAX_CHARS, PREFILL_REASON) };
+    if (prompt.length > BRIEF_TEXT_MAX_CHARS)
+        return { ok: false, error: tooLongMessage("the new brief", prompt.length, BRIEF_TEXT_MAX_CHARS, PREFILL_REASON) };
     if (prompt.includes(PROMPT_START) || prompt.includes(PROMPT_END))
         return { ok: false, error: "the new brief contains a tumwater:prompt marker, which would break the block for every reader" };
     const file = briefPath(root);
     if (file === null)
         return { ok: false, error: NO_BRIEF };
     const name = path.basename(file);
-    const changed = withStateLock(primaryWorktreeLockPath(root), () => {
+    const changed = withPrimaryWorktreeLock(root, () => {
         const current = fs.readFileSync(file, "utf8");
-        const next = replaceInitialPrompt(current, prompt);
+        const next = replaceBriefText(current, prompt);
         if (next === null)
             return `${name} no longer carries a prompt block`;
         if (next === current)