tumwater 0.2.0 → 0.4.0

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

@@ -0,0 +1,51 @@
+/** The operator's deliberate acceptance of a pending post-merge review without running it
+ * (src/cli/cli-review-commands.ts `tumwater reviews --accept <n>`), split out of the CLI so
+ * the review queue stays a pure reader/editor and this module owns the destructive half —
+ * removing an unattempted entry on purpose. It is the sibling of `tumwater queue --cancel
+ * <n>` (src/merge/merge-cancel.ts): the queue's no-third-path gap that the at-risk alert's
+ * shared sentence names ("…or accept the commit unreviewed deliberately"). It reads the same
+ * FIFO list `readPostReviews` numbers 1..N and settles the entry by its commit, so the removed
+ * entry is the very one the printed position named. */
+import { readPostReviews, settlePostReview } from "./post-merge-review.js";
+import { warnEventBestEffort } from "../events/events.js";
+import { shortSha } from "../text/format.js";
+/** Remove one readable entry the operator accepts unreviewed: refuse it (writing nothing) when
+ * it carries `fixed` — the repair already merged, so accepting it unreviewed is meaningless
+ * and the false "accepted unreviewed" warning would mislead — otherwise settle it with no
+ * verdict (`settlePostReview`; its failed write already warns and never throws, INV-BT2),
+ * log one `warning` under the entry's role, and return the `accepted` outcome naming what was
+ * retired. A rejected entry waits on nothing, so it is accepted like any other pending entry.
+ * The single removal both `acceptPostReview` (by position) and `acceptPostReviewBySha`
+ * (by sha) share, so the CLI and the dashboard's post-review-accept cannot drift on what
+ * accepting means. */
+function removeAcceptedEntry(root, entry) {
+    if (entry.fixed !== undefined)
+        return { status: "settled", commit: entry.commit };
+    settlePostReview(root, entry.commit, null);
+    const message = `post-merge review of ${shortSha(entry.commit)} accepted unreviewed at the operator's request — the commit stays on main unreviewed`; // vocabulary-ok: the accepted-unreviewed wording those reasons it is the operator's choice
+    warnEventBestEffort(root, entry.role, message);
+    return { status: "accepted", role: entry.role, commit: entry.commit, summary: entry.summary };
+}
+/** Retire the Nth pending post-merge review — 1-based, as `tumwater reviews` numbers it —
+ * accepting the commit unreviewed at the operator's request. `position` is resolved against
+ * `readPostReviews` (the same readable FIFO list the command renders), so the position matches
+ * the line `tumwater reviews` printed. An out-of-range position writes nothing and returns the
+ * current readable depth; otherwise it runs the same `removeAcceptedEntry` the sha variant
+ * shares, so the two never drift on what accepting means (see `removeAcceptedEntry` for the
+ * removal, the fixed-guard, the warning, and the never-throws guarantee). */
+export function acceptPostReview(root, position) {
+    const entries = readPostReviews(root);
+    if (position < 1 || position > entries.length)
+        return { status: "out-of-range", depth: entries.length };
+    return removeAcceptedEntry(root, entries[position - 1]);
+}
+/** Remove the pending post-merge review whose entry's commit is `sha` (the browser twin of
+ * `tumwater reviews --accept <n>`, resolving by commit because the dashboard rows carry one).
+ * A commit that matches none is `{ status: "gone" }` and changes nothing; otherwise it runs the
+ * same `removeAcceptedEntry` the position variant shares. */
+export function acceptPostReviewBySha(root, sha) {
+    const entry = readPostReviews(root).find((e) => e.commit.toLowerCase() === sha.toLowerCase());
+    if (!entry)
+        return { status: "gone" };
+    return removeAcceptedEntry(root, entry);
+}

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

@@ -0,0 +1,112 @@
+/** The renderer behind `tumwater reviews` — the operator-facing text for the post-merge review
+ * queue (.tumwater/state/post-review.json): one line per well-formed entry in the given order,
+ * plus a `post-merge review queue (N):` header. Pure function of the entry list — the optional
+ * `now` is the only clock input, and when it is a number and an entry carries `enqueuedAt` the
+ * line names the wait since the entry was first queued, exactly as the merge queue names its
+ * age — so a test can pin its output exactly. The `merge queue empty` convention
+ * (src/merge/merge-queue-render.ts) is reused for the empty case. */
+import { roleLabel } from "../roles/role-labels.js";
+import { shortSha } from "../text/format.js";
+import { squash } from "../text/text.js";
+import { filterKeepPositions } from "../collections.js";
+import { plural } from "../text/phrases.js";
+import { humanAgo } from "../text/datetime.js";
+/** The one state every observer surface narrows on: `fixed` when the repair already merged
+ * (the terminal Forward-never-back 1a/6 record — naming both shas, it is not pending anything),
+ * `rejected` when the reviewer turned the commit back (empty `rejected` array still counts),
+ * `failing` when the review runs keep ending without a verdict (`failures` positive), else
+ * `waiting`. The precedence matches what postReviewStatusLabel already printed — an entry can
+ * never be both — so the status label and `tumwater reviews --status` share this one definition
+ * and cannot drift. */
+export function postReviewState(entry) {
+    if (entry.fixed !== undefined)
+        return "fixed";
+    if (entry.rejected !== undefined)
+        return "rejected";
+    if (typeof entry.failures === "number" && entry.failures > 0)
+        return "failing";
+    return "waiting";
+}
+/** The states `tumwater reviews --status` accepts, in the order the filter's error message
+ * lists them (the terminal `fixed` last). `postReviewState` is the definition; this only names
+ * the vocabulary. */
+export const POST_REVIEW_STATES = ["waiting", "failing", "rejected", "fixed"];
+/** The bracketed status suffix one post-merge review entry carries on every observer surface
+ * (`tumwater reviews`, the dashboard's Post-merge reviews card, and the TUI Pending pane's
+ * review block): the reviewer's recorded rejected reasons when `rejected` is set; else the
+ * number of verdict-less review runs when `failures` is positive, naming the
+ * last failure's reason beside the count when `lastFailure` is a non-empty string; else `""`.
+ * Reasons are squashed to 60 as `tumwater reviews` has always printed them, and the failure
+ * detail to 80. Branches on `postReviewState` so the label and the `--status` filter share one
+ * state definition; extracted so the
+ * CLI, the dashboard and the TUI share one status wording and cannot drift. */
+export function postReviewStatusLabel(entry) {
+    switch (postReviewState(entry)) {
+        case "fixed":
+            return `[fixed — the repair ${shortSha(entry.fixed)} already merged on main]`;
+        case "rejected":
+            return `[rejected — ${entry.rejected.map((r) => squash(r, 60)).join("; ")}]`;
+        case "failing": {
+            const failures = entry.failures; // postReviewState only says "failing" when failures > 0
+            if (typeof entry.lastFailure === "string" && entry.lastFailure.length > 0) {
+                return `[${plural(failures, "failed review run")} — last: ${squash(entry.lastFailure, 80)}]`;
+            }
+            return `[${plural(failures, "failed review run")}]`;
+        }
+        default:
+            return "";
+    }
+}
+/** Narrows a whole post-merge review list to the entries `keep` accepts, and returns
+ * the `scope` renderPostReviews takes: the kept roles, each kept entry's 1-based place in the
+ * whole list, and the whole list's entry count — plus, when a status filter is active, the
+ * `filter` text the header and no-match line print. The filtering-and-positioning step is the
+ * shared `filterKeepPositions` (src/collections.ts) that `scopeMergeQueue` (src/merge/
+ * merge-queue-render.ts) also uses, so `tumwater reviews --role` keeps the same whole-queue
+ * positions `--accept <n>` still addresses. */
+export function scopePostReviews(entries, roles, keep, filter) {
+    const { kept, positions } = filterKeepPositions(entries, keep);
+    return {
+        entries: kept,
+        scope: { roles, positions, total: entries.length, ...(filter !== undefined ? { filter } : {}) },
+    };
+}
+/** The text `tumwater reviews` prints. A totally empty queue renders `post-merge review queue
+ * empty`; otherwise a header and one line per entry — position, role, short commit, and, when
+ * `now` and the entry's `enqueuedAt` are both numbers, the wait since the commit was queued
+ * (`<age> ago`, between the short commit and the summary) — then the squashed summary and the
+ * status suffix from `postReviewStatusLabel`, appended as `" · " + label` only when it is
+ * non-empty. Without a `now`, or for an entry with no `enqueuedAt`, the line is byte-identical
+ * to before, so an older `post-review.json` and every existing renderer test read unchanged.
+ * With the optional `scope` (`reviews --role`/`--status`: `entries` already holds only the kept
+ * entries', `positions` their 1-based places in the whole queue, `total` the whole queue's
+ * entry count, and `filter` the `--role`/`--status` filter text when one is active) each line
+ * keeps its whole-queue number and the header reads
+ * `post-merge review queue (<kept> of <total>, <filter>):`, where `<filter>` is `scope.filter`
+ * when set else `--role <ids>`. A scope that keeps nothing of a non-empty queue prints
+ * `no post-merge reviews matching <filter> (post-merge review queue holds <total>)` when a
+ * filter is set, else `no post-merge reviews for <ids> (…)`. Without `scope` and `now` the
+ * output is byte-identical to before. */
+export function renderPostReviews(entries, scope, now) {
+    const total = scope ? scope.total : entries.length;
+    if (total === 0)
+        return "post-merge review queue empty";
+    if (scope && entries.length === 0) {
+        const reason = scope.filter !== undefined ? `matching ${scope.filter}` : `for ${scope.roles.join(",")}`;
+        return `no post-merge reviews ${reason} (post-merge review queue holds ${total})`;
+    }
+    const lines = [
+        scope
+            ? `post-merge review queue (${entries.length} of ${total}, ${scope.filter ?? `--role ${scope.roles.join(",")}`}):`
+            : `post-merge review queue (${plural(total, "entry", "entries")}):`,
+    ];
+    entries.forEach((entry, i) => {
+        const label = postReviewStatusLabel(entry);
+        const suffix = label === "" ? "" : ` · ${label}`;
+        const age = typeof now === "number" && typeof entry.enqueuedAt === "number"
+            ? ` · ${humanAgo(entry.enqueuedAt, now)}`
+            : "";
+        lines.push(`  ${scope ? scope.positions[i] : i + 1}. ${roleLabel(entry.role)} ${shortSha(entry.commit)}${age} · ${squash(entry.summary, 80)}${suffix}`);
+    });
+    return lines.join("\n");
+}

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

@@ -0,0 +1,239 @@
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { postReviewPath, postReviewWorktreePath, nativeLogPath, piLogPath, reviewRunSessionDir, reviewFixRef } from "../paths.js";
+import { reviewedAfterMerge, 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 { commitAll, deleteRef, setRef } from "../git/git.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 { shortSha } from "../text/format.js";
+import { errorMessage } from "../text/text.js";
+import { revisionRoundOf } from "../git/commit-message.js";
+import { REVISION_BACKSTOP } from "../runner/revision.js";
+import { eventRole } from "../events/event-read.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { fixLine } from "../verdict/reply-contract.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;
+/** The bar a day's post-merge rejections must reach before the `post-merge-churn` amber alert
+ * (src/ui/team-alerts.ts) fires: one post-merge rejection is the tiering's ordinary cost, two in
+ * a day is a role whose already-landed changes keep being turned back — the reviewer-fix signal
+ * for an operator to narrow `review.afterMerge` or raise the authoring bar. */
+export const POST_MERGE_REJECT_WARN = 2;
+/** How far back the post-merge-churn rule looks — one day, the 24 h event-window convention
+ * every event-reading alert uses (PRIMARY_OVERWRITE_WINDOW_MS sorts beside it). */
+export const POST_MERGE_REJECT_WINDOW_MS = 24 * 60 * 60_000;
+/** Group the `afterMerge: true` `review_rejected` events of `events` by base role — the same
+ * `e.type === "review_rejected" && e.afterMerge === true` test the report fold
+ * (src/report/report-fold.ts `postMergeRejectionsByRole`) applies, so the churn alert and the
+ * report cannot disagree on which rejections are post-merge. The key is the event's base role
+ * (`baseRoleOf(eventRole(ev))`), not the raw source: an event's `source` is the runner id
+ * (`bugfix-2`), and both the alert's remedy ("narrow `review.afterMerge`") and the scoped
+ * report are keyed by base role, so one base role's churn must read as one row. Pre-merge
+ * rejections and other event types contribute nothing. */
+export function postMergeRejectionCounts(events) {
+    const byRole = new Map();
+    for (const ev of events) {
+        if (ev.type === "review_rejected" && ev.afterMerge === true) {
+            const role = baseRoleOf(eventRole(ev));
+            byRole.set(role, (byRole.get(role) ?? 0) + 1);
+        }
+    }
+    return [...byRole.entries()]
+        .map(([role, count]) => ({ role, count }))
+        .sort((a, b) => b.count - a.count || (a.role < b.role ? -1 : a.role > b.role ? 1 : 0));
+}
+/** The one home of the trigger and selection the `post-merge-churn` alert (src/ui/team-alerts.ts)
+ * and the doctor's `post-merge churn` row (src/doctor/doctor-project-checks.ts) share: whether
+ * the trailing `POST_MERGE_REJECT_WINDOW_MS` holds at least `POST_MERGE_REJECT_WARN` post-merge
+ * `review_rejected` events, and, when it does, which roles and how many each. null when the
+ * window holds fewer than the bar, or none — so the two surfaces cannot disagree on when churn
+ * fires. */
+export function postMergeChurn(events) {
+    const roles = postMergeRejectionCounts(events);
+    const count = roles.reduce((n, r) => n + r.count, 0);
+    return count >= POST_MERGE_REJECT_WARN ? { count, roles } : null;
+}
+/** Whether `role`'s changes are reviewed after merging instead of before. One home for the
+ * membership test, config-views.ts's reviewedAfterMerge — the same predicate the review gate,
+ * the runner's `already_queued` recovery arm and the role view read. */
+export function isAfterMergeRole(config, role) {
+    return reviewedAfterMerge(config, 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 — a non-string `lastFailure` is dropped like the
+ * other fields) 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, lastFailure, rejected, enqueuedAt, fixed } = 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 (typeof lastFailure === "string")
+            entry.lastFailure = lastFailure;
+        if (Array.isArray(rejected))
+            entry.rejected = rejected.filter((r) => typeof r === "string");
+        if (typeof fixed === "string")
+            entry.fixed = fixed;
+        if (typeof enqueuedAt === "number" && Number.isFinite(enqueuedAt) && enqueuedAt >= 0)
+            entry.enqueuedAt = enqueuedAt;
+        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. Stamps `enqueuedAt` when the entry carries none —
+ * the file's existing stamp on a re-add of a known commit, else `now` (the default clock when the
+ * write path drives the drain) — so a re-queued entry keeps its original stamp and tests can pin
+ * a fixed instant. */
+export function addPostReview(root, entry, now = Date.now()) {
+    const rest = readPostReviews(root);
+    const prior = rest.find((e) => e.commit === entry.commit)?.enqueuedAt;
+    const stamped = { ...entry, enqueuedAt: entry.enqueuedAt ?? prior ?? now };
+    writePostReviews(root, [...rest.filter((e) => e.commit !== entry.commit), stamped]);
+}
+/** 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);
+}
+/** Cut a review finding's first reason short enough to ride a commit subject (the
+ * `tumwater(reviewer): Fix …` subject names it): trimmed of leading/trailing and repeated
+ * whitespace, clipped at a word boundary around 100 chars with an ellipsis. */
+function clipFixReason(reason) {
+    const trimmed = reason.trim().replace(/\s+/g, " ");
+    if (trimmed.length <= 100)
+        return trimmed;
+    return `${trimmed.slice(0, 97).replace(/\s+\S*$/, "")}…`;
+}
+/** Commit the review worktree's edited paths as the one `tumwater(reviewer): Fix <short sha> —
+ * <first finding>` fix commit, made by the harness's own git call (never pi) — commitAll stages
+ * and commits everything, so however the reviewer edited a path, the single commit captures it
+ * on top of the reviewed commit C (the detached HEAD the worktree reset to); the caller advances
+ * the review-fix ref to the returned sha. The harness stamps the fix's body with the `Revision:`
+ * trailer one past the reviewed commit's round, so the next review of the fix reads its own round
+ * from the same place a rejection's hand-back reads it (Forward never back 2/6) and the self-fix
+ * chain counts toward the shared REVISION_BACKSTOP. Returns the new commit's full sha. */
+async function commitReviewerFix(wt, commit, reasons, nextRound) {
+    const first = reasons[0] ? clipFixReason(reasons[0]) : "the reviewed change";
+    const subject = `tumwater(reviewer): Fix ${shortSha(commit)} — ${first}`;
+    const body = reasons.map((r, i) => `${i + 1}. ${r}`).join("\n");
+    const withRound = body ? `${body}\nRevision: ${nextRound}` : `Revision: ${nextRound}`;
+    return commitAll(wt, `${subject}\n\n${withRound}`);
+}
+/** 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 fixRef = reviewFixRef(commit);
+        // The whole review — the detached checkout, the reviewer run, and (on a repair) the status
+        // read, the fix commit and its ref — runs under one hold of the post-review worktree
+        // (plans/disk-floor.md part 2/4), so nothing can reset or reuse the shared worktree between
+        // the reviewer's edit and the commit that captures it.
+        return await useWorktree(root, postReviewWorktreePath(root), async () => {
+            // The review-fix ref tracks the reviewed commit C (and later the reviewer's fix commit), so
+            // a repair survives as a durable reachable ref the pin housekeeping sees. The ref is reset
+            // to C at every review and ensureDetachedWorktree hard-resets the worktree to C, so a
+            // leftover ref or edit from an earlier review cannot change what is reviewed. Checking the
+            // worktree out at C itself (not the ref) keeps the "git could not start" semantics of the
+            // detached checkout it replaces: a review whose git cannot start throws gitCouldNotStart.
+            const wt = await ensureDetachedWorktree(root, postReviewWorktreePath(root), commit);
+            await setRef(root, fixRef, commit);
+            const diff = await git(wt, "diff", `${commit}^`, commit);
+            logEventBestEffort(root, { source: role, type: "review_start", head: commit, afterMerge: true });
+            const pi = await runGatePi({
+                cwd: wt,
+                kind: "gate",
+                prompt: buildReviewPrompt(diff, entry.summary, entry.body, readPrinciples(root), undefined, `${commit}^`, undefined, undefined, undefined, true),
+                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) {
+                await deleteRef(root, fixRef);
+                return { kind: "failed", detail: pi.errorMessage ?? "no parseable VERDICT line in the reviewer's reply" };
+            }
+            const durationMs = Date.now() - startedAt;
+            // One record for the reviewed commit C whatever way the review ends — reject or approve —
+            // so the fix-forward landing does not lose the verdict that motivated it.
+            if (verdict.verdict === "reject") {
+                logEventBestEffort(root, { source: role, type: "review_rejected", head: commit, reasons: verdict.reasons, durationMs, afterMerge: true });
+            }
+            else {
+                logEventBestEffort(root, { source: role, type: "review_verdict", head: commit, reason: verdict.reasons[0], durationMs, afterMerge: true });
+            }
+            // A rejecting review whose reply carries a FIX: line and whose worktree holds an edit
+            // survives as one fix commit on the review ref, kept for merge-post-review.ts to land on
+            // main through the ordinary change path. A clean worktree or a reply with no FIX line keeps
+            // today's outcomes and deletes the ref.
+            const paths = pi.ok && !pi.aborted ? fixLine(pi.verdictText ?? "") : null;
+            if (paths && verdict.verdict === "reject" && (await gitTry(wt, "status", "--porcelain"))?.trim().length) {
+                // The self-fix chain's round is one past the reviewed commit's `Revision:` trailer; at
+                // REVISION_BACKSTOP the reviewer stops fixing and records the surviving findings — the
+                // same terminal stop as a rejection's exhaustion, one shared counter, never a second
+                // one (Forward never back 2/6). The answered plan is deliberately NOT held here: it was
+                // already archived to PLANS-DONE.md when its implementation landed, so it is no longer
+                // under `## Planned` and there is nothing left to hold or re-pick.
+                const reviewedMessage = (await gitTry(root, "log", "-1", "--format=%B", commit)) ?? "";
+                const nextRound = (revisionRoundOf(reviewedMessage) ?? 0) + 1;
+                if (nextRound >= REVISION_BACKSTOP) {
+                    await deleteRef(root, fixRef); // the chain stops here; nothing to land
+                    logEventBestEffort(root, {
+                        source: entry.role,
+                        type: "revision",
+                        action: "exhausted",
+                        round: nextRound,
+                        sha: commit,
+                    });
+                    return { kind: "exhausted", reasons: verdict.reasons };
+                }
+                const fix = await commitReviewerFix(wt, commit, verdict.reasons, nextRound);
+                // Advance the review-fix ref from C to the new fix commit, so the repair is reachable and
+                // the merge-post-review landing (which checks the fix out by this sha) finds it.
+                await setRef(root, fixRef, fix);
+                return { kind: "fixed", fix, reasons: verdict.reasons };
+            }
+            await deleteRef(root, fixRef);
+            if (verdict.verdict === "reject")
+                return { kind: "reject", reasons: verdict.reasons };
+            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,23 +1,25 @@
-// 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 —
- * 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. */
-export async function protectedEditReason(wt, mainBranch, files, role) {
+/** The deterministic gate/stage finding for a change that edits the brief text block of a brief
+ * file (changed, removed, or the file deleted — a block that only moves passes); the role-
+ * independent half of protectedEditReason, split out so the main watch still runs it when it
+ * cannot name the tip's merging role (an unknown role is no basis for calling a PRINCIPLES.md
+ * edit unauthorized, but the brief block forbids its edit for every role alike): a brief edit
+ * could otherwise land on main un-watched ("Every commit is verified on main, part 1/3").
+ * undefined when no brief-file change touches the block. Reads the worktree and the change's
+ * baseRev (a commit or branch) like backlogStructureReason; a missing file reads as empty and
+ * never throws. */
+export async function briefEditReason(wt, baseRev, files) {
     const briefs = BRIEF_FILES.filter((f) => files.includes(f));
     if (briefs.length > 0) {
-        const baseRev = await changeBaseRev(wt, mainBranch);
         for (const file of briefs) {
             const base = promptBlockOf(await fileContentAt(wt, baseRev, file));
             if (base === null)
@@ -27,6 +29,18 @@ export async function protectedEditReason(wt, mainBranch, files, role) {
                 return `${file} changes the brief between the tumwater:prompt markers — only you edit it (tumwater brief); restore the block`;
         }
     }
+    return undefined;
+}
+/** 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. */
+export async function protectedEditReason(wt, mainBranch, files, role) {
+    const baseRev = await changeBaseRev(wt, mainBranch);
+    const brief = await briefEditReason(wt, baseRev, files);
+    if (brief !== undefined)
+        return brief;
     if (files.includes("PRINCIPLES.md") && !PRINCIPLES_ROLES.has(baseRoleOf(role)))
         return `PRINCIPLES.md is edited by the ${role} role — only the director and steward roles may edit it; record an objection in PLANS.md instead and revert the edit`;
     return undefined;

package/dist/src/review/quarantine-render.js

@@ -0,0 +1,65 @@
+/** The read-only render of the review gate's flake quarantine for the `tumwater
+ * quarantine` command. The quarantine list (.tumwater/state/quarantine.json) is the tests
+ * that failed then passed on the same tree; the doctor's `flaky checks` row and the
+ * selfcheck digest share the underlying quarantineWarning, and this module renders the full
+ * list — every entry oldest first with its age, flake count, last sighting and filed bug —
+ * so an operator can see which tests the gate is excusing and why. Pure over its inputs
+ * (no I/O, no clock): every branch has its own unit tests. */
+import { plural } from "../text/phrases.js";
+import { squash } from "../text/text.js";
+import { humanAgo } from "../text/datetime.js";
+import { quarantineWarning } from "../baseline/main-guardrails.js";
+/** The quarantine as sorted, positioned rows, oldest first (firstSeen ascending, the order
+ * quarantineWarning names its oldest), ties by test name, numbered 1..N. `bug` passes
+ * through with `""` staying `""`. */
+export function quarantineRows(entries) {
+    return [...entries]
+        .sort((a, b) => a.firstSeen - b.firstSeen || (a.test < b.test ? -1 : a.test > b.test ? 1 : 0))
+        .map((e, i) => ({
+        position: i + 1,
+        test: e.test,
+        firstSeen: e.firstSeen,
+        lastSeen: e.lastSeen,
+        count: e.count,
+        bug: e.bug,
+    }));
+}
+/** The command's text for `rows`: an empty list prints the empty line (the merge queue empty
+ * convention), otherwise a `flake quarantine: N tests` header, the shared quarantineWarning
+ * phrase on its own line when one fires (so the command and the doctor's row agree), then one
+ * numbered line per entry naming its test, first-seen and last-seen age, flake count and the
+ * BUGS.md heading filed for it (or "not filed"). */
+export function renderQuarantine(rows, now) {
+    if (rows.length === 0)
+        return "flake quarantine is empty";
+    const lines = [`flake quarantine: ${plural(rows.length, "test")}`];
+    const warning = quarantineWarning(rows, now);
+    if (warning !== null)
+        lines.push(warning);
+    for (const r of rows) {
+        const filed = r.bug ? ` — filed: ${squash(r.bug, 80)}` : " — not filed";
+        lines.push(`${r.position}. ${squash(r.test, 80)} — first seen ${humanAgo(r.firstSeen, now)}, ` +
+            `last seen ${humanAgo(r.lastSeen, now)}, ${plural(r.count, "flake")}${filed}`);
+    }
+    return lines.join("\n");
+}
+/** The Markdown section the Failures surfaces (the dashboard's Failures view and the TUI's
+ * Failures pane) append below the failure digest — the read twin of the amber quarantine
+ * alert, whose `See failures` action lands there. It reads the same `quarantineRows` rule as
+ * `tumwater quarantine` (and shares its `quarantineWarning` phrase when one fires), so the CLI
+ * and the always-on surfaces cannot disagree. Empty for an empty list, so a window with a
+ * digest but a clean quarantine adds nothing. Pure over its inputs (no I/O, no clock). */
+export function renderQuarantineSection(rows, now) {
+    if (rows.length === 0)
+        return "";
+    const lines = ["## Flake quarantine", ""];
+    const warning = quarantineWarning(rows, now);
+    if (warning !== null)
+        lines.push(warning, "");
+    for (const r of rows) {
+        const filed = r.bug ? `filed: ${squash(r.bug, 80)}` : "not filed";
+        lines.push(`- ${squash(r.test, 80)} — first seen ${humanAgo(r.firstSeen, now)}, ` +
+            `last seen ${humanAgo(r.lastSeen, now)}, ${plural(r.count, "flake")} — ${filed}`);
+    }
+    return lines.join("\n");
+}

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.