tumwater 0.2.0 → 0.3.0

package/dist/src/review/post-merge-review.js

@@ -0,0 +1,106 @@
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { postReviewPath, postReviewWorktreePath, nativeLogPath, piLogPath, reviewRunSessionDir } from "../paths.js";
+import { reviewRunConfig } from "../config/config-views.js";
+import { logEventBestEffort, TUMWATER_SOURCE, tryOrWarn } from "../events/events.js";
+import { isJsonObject } from "../files/json-object.js";
+import { git, gitCouldNotStart, gitTry } from "../git/git-run.js";
+import { ensureDetachedWorktree } from "../git/worktree.js";
+import { useWorktree } from "../git/worktree-use.js";
+import { readPrinciples } from "../prompt/principles.js";
+import { buildReviewPrompt } from "../prompt/gate-prompts.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { shortSha } from "../text/format.js";
+import { errorMessage } from "../text/text.js";
+import { parseVerdict } from "./review-verdict.js";
+/** A commit's review is dropped, with a warning, after this many runs with no verdict. */
+export const POST_REVIEW_FAILURE_LIMIT = 3;
+/** Whether `role`'s changes are reviewed after merging instead of before. */
+export function isAfterMergeRole(config, role) {
+    return (config.review.afterMerge ?? []).includes(baseRoleOf(role));
+}
+/** The queued entries. A torn or hand-edited entry (not an object with a string commit, role and
+ * summary, or a `rejected` that is not an array) is dropped, and the next write leaves it out. */
+export function readPostReviews(root) {
+    const saved = readJsonFile(postReviewPath(root));
+    if (!Array.isArray(saved?.pending))
+        return [];
+    const entries = [];
+    for (const raw of saved.pending) {
+        if (!isJsonObject(raw))
+            continue;
+        const { commit, role, summary, body, failures, rejected } = raw;
+        if (typeof commit !== "string" || typeof role !== "string" || typeof summary !== "string")
+            continue;
+        if (rejected !== undefined && !Array.isArray(rejected))
+            continue;
+        const entry = { commit, role, summary };
+        if (typeof body === "string")
+            entry.body = body;
+        if (typeof failures === "number" && Number.isFinite(failures))
+            entry.failures = failures;
+        if (Array.isArray(rejected))
+            entry.rejected = rejected.filter((r) => typeof r === "string");
+        entries.push(entry);
+    }
+    return entries;
+}
+function writePostReviews(root, pending) {
+    tryOrWarn(root, TUMWATER_SOURCE, "write post-review.json", () => writeJsonAtomic(postReviewPath(root), { pending }));
+}
+/** Queue the merged commit for its review. Never throws: a failed write warns and leaves the file
+ * as it was, so the commit goes unreviewed. */
+export function addPostReview(root, entry) {
+    writePostReviews(root, [...readPostReviews(root).filter((e) => e.commit !== entry.commit), entry]);
+}
+/** Replace the entry for `commit` with `next`, or drop it when `next` is null. Never throws: a
+ * failed write warns and leaves the file as it was, so a later poll handles the entry again. */
+export function settlePostReview(root, commit, next) {
+    const rest = readPostReviews(root).filter((e) => e.commit !== commit);
+    writePostReviews(root, next ? [...rest, next] : rest);
+}
+/** Review the merged commit C: the usual reviewer prompt over `git diff C^ C`, run in a detached
+ * checkout of C. Logs `review_start` and `review_verdict` / `review_rejected` with
+ * `afterMerge: true`. A diff git fails to produce is a failed review with no reviewer run: read
+ * as empty, the reviewer approved a commit it never saw. Throws only when git could not start
+ * (gitCouldNotStart), which says nothing about C, so the caller keeps the entry as it was for
+ * the next poll instead of counting a failed run toward dropping it. */
+export async function reviewMergedCommit(root, config, entry, runGatePi, signal) {
+    const { commit, role } = entry;
+    try {
+        const reviewCfg = reviewRunConfig(config);
+        const startedAt = Date.now();
+        const pi = await useWorktree(root, postReviewWorktreePath(root), async () => {
+            const wt = await ensureDetachedWorktree(root, postReviewWorktreePath(root), commit);
+            await gitTry(wt, "checkout", "--detach", "--force", commit);
+            const diff = await git(wt, "diff", `${commit}^`, commit);
+            logEventBestEffort(root, { source: role, type: "review_start", head: commit, afterMerge: true });
+            return runGatePi({
+                cwd: wt,
+                kind: "gate",
+                prompt: buildReviewPrompt(diff, entry.summary, entry.body, readPrinciples(root), undefined, `${commit}^`),
+                config: reviewCfg,
+                sessionDir: reviewRunSessionDir(root, role, `post-${shortSha(commit)}`),
+                sessionName: `tumwater-review-${role}-post-${shortSha(commit)}`,
+                rawLogFile: piLogPath(root, role),
+                nativeLogFile: nativeLogPath(root, role, reviewCfg.agent ?? "pi"),
+                label: "review",
+                signal,
+            });
+        });
+        const verdict = pi.ok && !pi.aborted ? parseVerdict(pi.verdictText ?? "") : null;
+        if (!verdict)
+            return { kind: "failed", detail: pi.errorMessage ?? "no parseable VERDICT line in the reviewer's reply" };
+        const durationMs = Date.now() - startedAt;
+        if (verdict.verdict === "reject") {
+            logEventBestEffort(root, { source: role, type: "review_rejected", head: commit, reasons: verdict.reasons, durationMs, afterMerge: true });
+            return { kind: "reject", reasons: verdict.reasons };
+        }
+        logEventBestEffort(root, { source: role, type: "review_verdict", head: commit, reason: verdict.reasons[0], durationMs, afterMerge: true });
+        return { kind: "approve", reasons: verdict.reasons };
+    }
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
+        return { kind: "failed", detail: errorMessage(err) };
+    }
+}

package/dist/src/review/protected-edits.js

@@ -1,16 +1,15 @@
-// vocabulary: plain
 import path from "node:path";
 import { promptBlockOf } from "../brief/brief.js";
 import { readTextOrNull } from "../files/files.js";
 import { changeBaseRev, fileContentAt } from "../git/git.js";
 import { briefCandidates } from "../paths.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
-/** The brief files that may carry the initial prompt block: the basenames of `briefCandidates`. */
+import { baseRoleOf } from "../roles/runner-ids.js";
+/** The brief files that may carry the brief text block: the basenames of `briefCandidates`. */
 const BRIEF_FILES = briefCandidates("").map((p) => path.basename(p));
 /** The roles that may edit PRINCIPLES.md. */
 const PRINCIPLES_ROLES = new Set(["director", "steward"]);
-/** The deterministic gate/stage finding for a change that edits what the loop prompts forbid
- * editing: the initial prompt block of a brief file (changed, removed, or the file deleted —
+/** The deterministic gate/stage finding for a change that edits what the role prompts forbid
+ * editing: the brief text block of a brief file (changed, removed, or the file deleted —
  * a block that only moves passes), or PRINCIPLES.md from a role other than director or
  * steward. undefined when neither happened. Reads the worktree and the change's merge-base
  * like backlogStructureReason; a missing file reads as empty and never throws. */

package/dist/src/review/review-followup.js

@@ -1,11 +1,11 @@
-import { agentSessionResumable } from "../agent/agent-backend.js";
-import { reviewRunConfig, resolvedAgentConfig } from "../config/config-views.js";
+import { backendSessionResumable } from "../agent/agent-backend.js";
+import { reviewRunConfig, resolvedBackendConfig } from "../config/config-views.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { nativeLogPath, piLogPath } from "../paths.js";
 import { buildNoRerunPrompt, buildVerdictRequestPrompt } from "../prompt/gate-prompts.js";
 import { cappedRequestTimeouts } from "../request-timeouts.js";
 /** Hard caps on the VERDICT follow-up turn: it should take one short reply on a warm session,
- * so it never gets the review run's own budget (mirrors LoopPi's SUMMARY-request caps). */
+ * so it never gets the review run's own budget (mirrors RunnerPi's SUMMARY-request caps). */
 const VERDICT_REQUEST_TIMEOUT_S = 900;
 const VERDICT_REQUEST_QUIET_S = 300;
 /** One bounded follow-up turn on the reviewer's just-finished session: the shared session
@@ -19,7 +19,7 @@ async function runFollowupTurn(ctx, opts) {
     // backend's own resumable rule keeps a newer line of another kind from being the session a
     // pi continue would actually reach; claude resumes its recorded id (looked up under the
     // team's config dir, so a team that set one continues under it).
-    if (!agentSessionResumable(dir, { kind: "gate", agent: cfg.agent ?? "pi" }, resolvedAgentConfig(ctx.config, "claude").configDir)) {
+    if (!backendSessionResumable(dir, { kind: "gate", agent: cfg.agent ?? "pi" }, resolvedBackendConfig(ctx.config, "claude").configDir)) {
         return null;
     }
     return ctx.runGatePi({
@@ -46,7 +46,7 @@ async function runFollowupTurn(ctx, opts) {
         onBlindRead: (path, action) => logEventBestEffort(ctx.root, {
             source: ctx.role,
             type: "image_blind",
-            run: ctx.tick,
+            run: ctx.runNumber,
             path,
             model: cfg.model,
             action,
@@ -55,14 +55,14 @@ async function runFollowupTurn(ctx, opts) {
     });
 }
 /** Ask the reviewer's own session (--continue) for the missing VERDICT line: one tightly
- * bounded turn on the just-finished review's session, mirroring LoopPi.requestSummary on the
+ * bounded turn on the just-finished review's session, mirroring RunnerPi.requestSummary on the
  * author side (BUGS.md 2026-09-29). Null when there is no session to continue — the caller
  * then counts the strike exactly as before. The run is returned even when it failed so the
  * caller can honor a shutdown abort and fold the spend. */
 export async function requestVerdict(ctx) {
     return runFollowupTurn(ctx, {
         prompt: buildVerdictRequestPrompt(),
-        sessionName: `tumwater-review-${ctx.role}-${ctx.tick}-verdict`,
+        sessionName: `tumwater-review-${ctx.role}-${ctx.runNumber}-verdict`,
         label: "review-verdict",
     });
 }
@@ -76,7 +76,7 @@ export async function requestVerdict(ctx) {
 export async function requestNoRerun(ctx, rerun, calls) {
     return runFollowupTurn(ctx, {
         prompt: buildNoRerunPrompt(rerun),
-        sessionName: `tumwater-review-${ctx.role}-${ctx.tick}-rerun`,
+        sessionName: `tumwater-review-${ctx.role}-${ctx.runNumber}-rerun`,
         label: "review-rerun",
         // Collected unconditionally: a nudge only runs after a detected rerun, so the no-re-run
         // rule stood and the repeat check below needs every call the nudge started.

package/dist/src/review/review-precheck.js

@@ -1,22 +1,48 @@
-// vocabulary: plain
 /** The review gate's deterministic build pre-check — split out of review.ts so the gate keeps
  * one responsibility (running the model reviewer and acting on its verdict) while this module
  * owns the pre-review verification: the one scoped build-check run, its flake re-run, the
- * sleep-unverified and main-red attributions, and the harness's own counts sentence. No model
+ * sleep-unverified and main-red attributions. No model
  * runs here — everything is decided by the project's declared check, so a deterministic
  * rejection never shows as "reviewing" on the dashboards and consumes no reviewer budget. */
 import { warnEventBestEffort } from "../events/events.js";
 import { BUILD_CHECK_TIMEOUT_MS } from "../build/build-check-detect.js";
 import { runScopedBuildCheck } from "../build/build-check-scoped.js";
-import { checkFailureReasons, describeCheck, failureHeadline } from "../build/build-check-report.js";
+import { checkFailureReasons, describeCheck, failureHeadline, FAILING_TESTS_MAX } from "../build/build-check-report.js";
 import { sleptPhrase, UNVERIFIED_TREE, unverifiedTreeOutcome } from "../build/build-check-events.js";
 import { sampleSleepClock } from "../build/host-sleep.js";
-import { recordReview } from "../tick/tick-apply.js";
+import { recordReview } from "../run/run-apply.js";
 import { mainRedNotMine } from "../text/phrases.js";
 import { shortSha } from "../text/format.js";
 import { checkWaitStage, setMergeStage } from "../merge/merge-slot.js";
 import { mainTipVerdict } from "../baseline/main-red.js";
-import { FLAKY_WARNING_PREFIX, isKnownFlake } from "./known-flakes.js";
+import { onlyKnownMainFailures } from "../baseline/main-watch.js";
+import { watchedBaseline } from "../baseline/main-baseline.js";
+import { changeBaseRev } from "../git/git.js";
+import { FLAKY_WARNING_PREFIX, isKnownFlake, quarantineTests } from "./known-flakes.js";
+/** The tests a gate failure shares with the change's own base, when that base is not main's tip:
+ * the main watch recorded the base red with every one of them. A branch behind a fix fails the
+ * old test on its base while main's tip is green (2026-10-20, report --role), so the tip verdict
+ * alone is the wrong question. Null when the failures are not all the base's, the list may have
+ * been cut short (the cap onlyKnownMainFailures uses), or git cannot say. */
+async function staleBaseFailures(wt, mainBranch, head, mainTip, failingTests) {
+    if (!failingTests || failingTests.length === 0 || failingTests.length >= FAILING_TESTS_MAX)
+        return null;
+    try {
+        const base = await changeBaseRev(wt, mainBranch, head);
+        if (base === mainTip)
+            return null;
+        const verdict = await watchedBaseline(wt, base);
+        if (verdict?.status !== "red")
+            return null;
+        const baseFailed = verdict.failingTests ?? [];
+        if (!failingTests.every((t) => baseFailed.includes(t)))
+            return null;
+        return { base, tests: [...failingTests] };
+    }
+    catch {
+        return null;
+    }
+}
 /** Run the gate's deterministic build pre-check. `reject` is the gate's one shared rejection
  * path (review.ts's reject closure): the pre-check routes a reproduced failure through it so
  * the bookkeeping (lastReview, branch reset, review_rejected event) cannot drift from the
@@ -41,10 +67,12 @@ export async function gateBuildPrecheck(ctx, state, head, reject) {
             // host were exactly that (BUGS.md 2026-09-23). The re-run is one more check, priced as
             // its own build_check event; if it passes, the tree is verified exactly like a
             // first-time pass and the flake is named in a warning (the headline clusters in the
-            // digest, so telemetry and bugfix can go after the flaky test). A re-run that fails
+            // digest, so selfcheck and bugfix can go after the flaky test). A re-run that fails
             // again goes to attribution below; a skipped one says nothing about the tree, so the
             // first failure stands.
-            const retry = await runGateCheck();
+            // A failure naming only known tests (main's, or quarantined) is judged below as it stands:
+            // a re-run could only repeat it.
+            const retry = onlyKnownMainFailures(root, outcome.failingTests) ? undefined : await runGateCheck();
             if (retry?.outcome.status === "passed") {
                 // When the failed run spanned a host sleep, the pass says the tree is fine and the
                 // sleep is the story — not a flaky test (BUGS.md 2026-09-30): the digest clusters
@@ -55,6 +83,8 @@ export async function gateBuildPrecheck(ctx, state, head, reject) {
                 else {
                     const flaky = failureHeadline(outcome.outputTail) ?? describeCheck(check);
                     warnEventBestEffort(root, role, `${FLAKY_WARNING_PREFIX}${flaky}`);
+                    // Each test the failed run named failed and then passed on this same tree: quarantined.
+                    quarantineTests(root, outcome.failingTests, outcome.outputTail);
                 }
                 outcome = retry.outcome;
             }
@@ -78,12 +108,23 @@ export async function gateBuildPrecheck(ctx, state, head, reject) {
             // host-sleep path above does. Before this, the repeat was attributed through main's
             // per-SHA baseline cache (usually a green seeded by an earlier merge), so a load- or
             // clock-sensitive test rejected whichever unrelated change hit it (BUGS.md 2026-10-06).
+            // The excuse is not a failure of the gate, so the change goes on to the model review
+            // instead of ending the merge attempt as review_error and paying a requeue. It carries no
+            // verifiedHead — the tree was not verified — so the merge
+            // path's own check still judges the tree before it reaches main.
             const flaky = failureHeadline(outcome.outputTail) ?? describeCheck(check);
+            // A failure that names only tests main already fails is main's, not this change's: it goes
+            // on to review with no fresh run on main. No verifiedHead — the tree did not pass, so the
+            // merge path must not seed a green for it — and the merge check judges it by the same rule.
+            const known = onlyKnownMainFailures(root, outcome.failingTests);
+            if (known) {
+                warnEventBestEffort(root, role, `gate check fails only main's known failures: ${known.join(", ")}`);
+                return { knownMainFailures: known };
+            }
+            // The headline excuse stays for a failure that names no test: quarantine covers named ones.
             if (isKnownFlake(root, flaky)) {
-                const detail = `known-flaky failure, merge kept: ${flaky}`;
-                recordReview(state, "failed", [detail], head);
-                warnEventBestEffort(root, role, detail);
-                return { resolved: { decision: "failed", detail, unverified: true } };
+                warnEventBestEffort(root, role, `known-flaky failure, merge kept: ${flaky}`);
+                return {};
             }
             const reasons = checkFailureReasons(check, outcome);
             // A failure that reproduced is attributed, never fixed here: the one merge slot the
@@ -106,14 +147,24 @@ export async function gateBuildPrecheck(ctx, state, head, reject) {
                 // Main fails too: not this change's failure. Leave the commit (and with it the pin) and
                 // do not advance the discard counter — the transport-failure rule (BUGS.md 2026-09-20):
                 // nothing judged this diff. main-red.ts's gate and the bugfix handoff own the repair,
-                // and the author's next tick re-merges the change once main is green again.
+                // and the orchestrator poll (requeueMainRedPin) re-queues the kept pin once main's head
+                // moves; leftover recovery holds it until then.
                 const detail = mainRedNotMine(main.sha);
                 recordReview(state, "failed", [detail], head);
                 warnEventBestEffort(root, role, `gate check failed on ${shortSha(head)}, but ${detail}; merge kept`);
                 return { resolved: { decision: "failed", detail, mainRed: true } };
             }
+            if (main.status === "green") {
+                const stale = await staleBaseFailures(wt, mainBranch, head, main.sha, outcome.failingTests);
+                if (stale) {
+                    // Same hand-off as the known-failure branch: no verifiedHead, so the merge check on the
+                    // rebased tree still judges it.
+                    warnEventBestEffort(root, role, `gate check fails only tests its base ${shortSha(stale.base)} already failed, and main ${shortSha(main.sha)} is green: ${stale.tests.join(", ")}; going on to review`);
+                    return { knownMainFailures: stale.tests };
+                }
+            }
             // Main green: the change broke the check — rejected deterministically through the shared
-            // reject path, no pi run consumed, reasons injected into the author's next tick. With no
+            // reject path, no pi run consumed, reasons injected into the author's next run. With no
             // verdict for main the author's failure is still the safe default, and the reasons say
             // the attribution could not be made.
             return {
@@ -126,17 +177,9 @@ export async function gateBuildPrecheck(ctx, state, head, reject) {
             // Passed: this exact tree just went green under the project's own declared check. Hand
             // the verdict to the merge path via verifiedHead — it seeds the red-main baseline with
             // the SHA that actually becomes main (the rebased head, which may differ from `head`),
-            // so every role's next fresh tick is a cache hit instead of one redundant full-suite
+            // so every role's next fresh run is a cache hit instead of one redundant full-suite
             // re-run on an already-verified tree.
-            // The counts are the harness's own reading of the runner's summary (parseTestCounts):
-            // attesting them here means neither the author nor the reviewer states a total, which is
-            // where most record-claim rejections came from (PLANS.md 2026-09-29).
-            return {
-                verifiedHead: head,
-                verifiedByHarness: outcome.counts
-                    ? `${describeCheck(check)} (the project's declared check) passed — ${outcome.counts.pass} pass, ${outcome.counts.fail} fail, ${outcome.counts.skipped} skipped of ${outcome.counts.tests}`
-                    : `${describeCheck(check)} (the project's declared check) passed`,
-            };
+            return { verifiedHead: head };
         }
     }
     return {};