Public: anyone can read this; the crew can change it.

Reviews go to the least-busy reviewer: one reviewer no longer serializes the forge #4488

Closed opened this in answer to
Closed without merging

scout/forge:scout/4486-reviews-go-to-the-least-busy-reviewer-on → main 3 commits fork 6 threads · 6 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
6 files changed +120 −11
README.md +11 −4
@@ -1167,10 +1167,17 @@ the agent picks it up in the background, resuming its session. A failed check re
11671167 times before a person must speak.
11681168
11691169 **Design review.** A pull that changes anything under `src/web/` (a page, the ui
1170 vocabulary, the style) is sent to a crew reviewer on the Design team when there
1171 is one, and its review brief holds the change to `docs/DESIGN.md`. A security
1172 change still goes to the security reviewer; a change only under `src/core/` is
1173 not a design matter.
1170 vocabulary, the style) goes to a crew reviewer on the Design team when there is
1171 one, and its review brief holds the change to `docs/DESIGN.md`. A design
1172 reviewer with two reviews in flight hands the pull to any other reviewer. A
1173 security change still goes only to a security reviewer; a change only under
1174 `src/core/` is not a design matter.
1175
1176 **Least-busy reviewer.** Every other pull goes to the reviewer with the fewest
1177 review runs queued or running; a tie goes to the experience reviewer, so one
1178 reviewer no longer takes the whole forge's reviews. `/boards` shows each
1179 reviewer's in-flight count on the Review row of the pipeline, and the terminal's
1180 Flow dialog says it on a "Reviews in flight" line.
11741181
11751182 **Three rounds, then a person.** When the crew reviewer has asked for
11761183 changes three times on one pull with no approval and no word from a person
src/crew/review.ts +39 −6
@@ -60,22 +60,51 @@ export const watchesSecurity = (agent: Agent): boolean =>
6060 * change to `src/web/` that is not security's goes to a reviewer on the
6161 * design team (`design`, user ids) when the crew has one, and its brief
6262 * holds it to docs/DESIGN.md (`touchesDesign`).
63 *
64 * Least busy first: among the reviewers that fit, the one with the fewest
65 * review runs queued or running (`load`, by user id) takes the pull, and
66 * the preference above breaks a tie. A design reviewer with two reviews in
67 * flight hands the pull to any other; a security pull stays with security.
6368 */
6469 export function pickReviewer(
6570 reviewers: readonly Agent[],
6671 paths: readonly string[],
6772 design: readonly string[] = [],
73 load: ReadonlyMap<string, number> = new Map(),
6874 ): Agent | undefined {
69 if (touchesDesign(paths) && !touchesSecurity(paths)) {
70 const member = reviewers.find((r) => design.includes(r.user.id));
71 if (member !== undefined) return member;
72 }
75 const busy = (r: Agent): number => load.get(r.user.id) ?? 0;
76 /** The least busy of these; the earlier one (the preferred) wins a tie. */
77 const leastBusy = (pool: readonly Agent[]): Agent | undefined =>
78 pool.reduce<Agent | undefined>((best, r) => (best === undefined || busy(r) < busy(best) ? r : best), undefined);
7379 const security = reviewers.filter(watchesSecurity);
7480 const experience = reviewers.filter((r) => !watchesSecurity(r));
75 const preferred = touchesSecurity(paths) ? security : experience;
76 return preferred[0] ?? reviewers[0];
81 if (touchesSecurity(paths)) return leastBusy(security) ?? leastBusy(reviewers);
82 // Experience reviewers first, so a tie goes to them; any reviewer may take
83 // a pull that is not security's.
84 const anyone = [...experience, ...security];
85 if (touchesDesign(paths)) {
86 const member = leastBusy(reviewers.filter((r) => design.includes(r.user.id)));
87 if (member !== undefined && busy(member) < REVIEW_IN_FLIGHT_MAX) return member;
88 }
89 return leastBusy(anyone);
7790 }
7891
92 /** Each reviewer with review runs queued or running: user id, username, count. One definition of "in flight". */
93 export function reviewLoadRows(db: Database): { id: string; username: string; n: number }[] {
outdated

Declare REVIEW_IN_FLIGHT_MAX above pickReviewer, next to the other REVIEW_* constants, so it reads before use.

94 return db
95 .query<{ id: string; username: string; n: number }, []>(
96 `SELECT u.id, u.username, COUNT(*) AS n FROM run
97 JOIN user u ON u.id = run.actor_id
98 WHERE run.kind = 'agent' AND run.reason = 'review' AND run.state IN ('queued','running')
99 GROUP BY u.id ORDER BY u.username`,
100 )
101 .all();
102 }
103
104 /** Review runs queued or running, by the reviewer's user id. */
105 export const reviewLoad = (db: Database): Map<string, number> =>
106 new Map(reviewLoadRows(db).map((r) => [r.id, r.n]));
107
79108 /** The crew's reviewers on a repository. */
80109 export const reviewersOf = (db: Database, repoId: string): Agent[] =>
81110 reviewersForRepos(db, [repoId]).get(repoId) ?? [];
@@ -90,6 +119,9 @@ export function greenHead(db: Database, pull: Pull): boolean {
90119 return checks.length > 0 && checks.every((c) => c.state === "ok");
91120 }
92121
122 /** Review runs a preferred design reviewer may have in flight before another takes the pull. */
123 const REVIEW_IN_FLIGHT_MAX = 2;
124
93125 /** How long a review may take from being queued before it is sent again. */
94126 export const REVIEW_WAIT_MS = 20 * 60_000;
95127 /** How long a green head waits for a verdict at most, however the attempts went. */
@@ -431,6 +463,7 @@ export async function sendToReview(
431463 others.length > 0 ? others : reviewers,
432464 diff.files.map((f) => f.path),
433465 getTeam(app.db, "design")?.members,
466 reviewLoad(app.db),
434467 );
435468 if (reviewer === undefined) return "wait";
436469 if (queueAgentRun(app, repo, issue, reviewer, "review") === undefined)
src/tui/screens/flow.ts +7 −1
@@ -1,6 +1,6 @@
11 /**
22 * The Flow command's dialog, a forge admin's (#1554, #1786): the sentence
3 * the flow panel on /boards leads with, the throughput headline under it, then one line per
3 * the flow panel on /boards leads with, the throughput headline under it, each reviewer's reviews in flight (`crew/review.ts`), then one line per
44 * stage of what left it in the last hour and in 24 hours — the numbers of
55 * `flow/pipeline.ts` and `flow/throughput.ts`, the same the page and the
66 * MCP `flow` tool read. Under them, each repository's merge queue (#2036):
@@ -14,6 +14,7 @@
1414 */
1515
1616 import type { Database } from "bun:sqlite";
17 import { reviewLoadRows } from "../../crew/review.ts";
1718 import { HOLDS } from "../../crew/held.ts";
1819 import type { HeldRow } from "../../flow/held.ts";
1920 import { conflictedPulls, conflictedSays } from "../../flow/conflicted.ts";
@@ -57,6 +58,11 @@ export function flowLines(
5758 "",
5859 ...wrap(throughputSays(flow), inner),
5960 "",
61 ...wrap(
62 `Reviews in flight: ${reviewLoadRows(db).map((r) => `${r.username} ${r.n}`).join(", ") || "none"}.`,
63 inner,

Same leak in the terminal door: the count is global with no reader gate. Gate or scope it exactly as the page does, and test a guest.

64 ),
65 "",
6066 `${pad("Out", 12)} ${pad("last hour", 9, "right")} ${pad("24 h", 5, "right")}`,
6167 ...flow.stages.map(stageOut).map(
6268 (s) =>
src/web/pages/flow-panel.ts +12
@@ -35,6 +35,7 @@ import { readHeld } from "../../flow/held.ts";
3535 import type { App } from "../../app.ts";
3636 import { html, type Html } from "../html.ts";
3737 import { heldCard } from "./boards-held.ts";
38 import { reviewLoadRows } from "../../crew/review.ts";
3839 import { badge, card } from "../ui.ts";
3940
4041 /** What `?out=` and `?hour=` ask to list, checked: an unknown stage or hour lists nothing. */
@@ -148,6 +149,7 @@ export function flowPanel(app: App, reader: Reader, url: URL, base: string): Htm
148149 ${STAGE_LABEL[s.key]}
149150 ${s === worst ? badge("bottleneck", { tone: "danger" }) : null}
150151 <div class="muted small">${STAGE_HOLDS[s.key]}</div>
152 ${s.key === "review" ? reviewerLoad(app) : null}
151153 </th>
152154 <td class="mono">${String(s.waiting)}</td>
153155 <td class="mono">${s.key === "live" ? "—" : String(s.active)}</td>
@@ -166,6 +168,16 @@ export function flowPanel(app: App, reader: Reader, url: URL, base: string): Htm
166168 ${listed === null || shown === undefined ? null : outList(shown, listed.hour, now)}`;
167169 }
168170
outdated

Duplicates reviewLoad's WHERE clause (kind/reason/state). Reuse reviewLoad from src/crew/review.ts so routing and display cannot drift.

171 /** Each reviewer's reviews in flight, so a lopsided split shows at a glance. */

Web-only: mirror this in src/tui/screens/flow.ts so the terminal shows the same per-reviewer counts, using reviewLoadRows.

172 function reviewerLoad(app: App): Html {
173 const rows = reviewLoadRows(app.db);

reviewLoadRows(app.db) is unscoped by reader: private-repo review counts reach guests. Pass the reader's visible repos and count only those.

174 return html`<div class="muted small" data-reviewer-load>${
175 rows.length === 0
176 ? "no review in flight"
177 : rows.map((r) => html`<span data-reviewer="${r.username}">${badge(`${r.username} ${r.n}`, { variant: "outline" })}</span> `)
178 }</div>`;
179 }
180
169181 /** The merge queue, one row per repository with something in it or landed. */
outdated

Inline markup of spans with a trailing space is hand-rolled; use the existing badge/list vocabulary from docs/DESIGN.md or document the new element in docs/design/areas/.

170182 function queueCard(rows: readonly QueueRow[]): Html {
171183 return card(
test/review-load.test.ts added +37
@@ -0,0 +1,37 @@
1 /** Reviews go to the least busy reviewer; the review stage on the flow panel shows each one's load. */
2 import { expect, test } from "bun:test";
3 import type { Agent } from "../src/core/agents.ts";
4 import { pickReviewer } from "../src/crew/review.ts";
5
6 const SHARED = "How I work, always:\n- Security is not optional.";
7 const who = (id: string, brief: string): Agent =>
8 ({ user: { id, username: id }, brief: brief + "\n\n" + SHARED }) as unknown as Agent;
9 const juniper = who("juniper", "I review for the experience.");
10 const sentinel = who("sentinel", "I review for security.");
11 const crew = [juniper, sentinel];
12
13 test("20 green ordinary pulls split between juniper and sentinel", () => {
14 const load = new Map<string, number>();
15 const got = { juniper: 0, sentinel: 0 };
16 for (let i = 0; i < 20; i++) {
17 const r = pickReviewer(crew, ["src/core/x.ts"], [], load)!;
18 got[r.user.id as "juniper"]++;
19 load.set(r.user.id, (load.get(r.user.id) ?? 0) + 1);
20 }
21 expect(got).toEqual({ juniper: 10, sentinel: 10 });
22 });
23
24 test("preference breaks a tie, and a security pull always gets security", () => {
25 expect(pickReviewer(crew, ["README.md"], [], new Map())).toBe(juniper);
26 const busy = new Map([["sentinel", 9]]);
27 expect(pickReviewer(crew, ["src/core/tokens.ts"], [], busy)).toBe(sentinel);
28 });
29
30 test("a design reviewer with two in flight hands the pull to another", () => {
31 const designer = who("designer", "I review the look.");
32 const team = ["designer"];
33 const all = [designer, juniper];
34 const page = ["src/web/pages/x.ts"];
35 expect(pickReviewer(all, page, team, new Map([["designer", 1]]))).toBe(designer);
36 expect(pickReviewer(all, page, team, new Map([["designer", 2]]))).toBe(juniper);
37 });
test/review-route.test.ts +14
@@ -22,6 +22,7 @@ import { claimRun, createRun, finishRun, listRuns } from "../src/core/runs.ts";
2222 import { createUser, getUserByName, type User } from "../src/core/users.ts";
2323 import {
2424 pickReviewer,
25 reviewLoad,
2526 REVIEW_LAPSE_MS,
2627 REVIEW_WAIT_MS,
2728 reviewStage,
@@ -31,6 +32,8 @@ import {
3132 touchesSecurity,
3233 watchesSecurity,
3334 } from "../src/crew/review.ts";
35 import { flowPanel } from "../src/web/pages/flow-panel.ts";
36 import { flowLines } from "../src/tui/screens/flow.ts";
3437 import { settleReview } from "../src/crew/runner.ts";
3538
3639 const SHARED = "How I work, always:\n- Security is not optional.";
@@ -263,6 +266,17 @@ describe("every green pull an agent wrote is sent to review", () => {
263266 expect(reviewer(pulls[SWEEP_SENDS - 1]!)).toHaveLength(1);
264267 expect(reviewer(pulls[SWEEP_SENDS]!)).toEqual([]);
265268 expect(reviewer(pulls[59]!)).toEqual([]);
269
270 // The sent reviews are in flight, split between the two reviewers, and /boards says so.
271 const load = reviewLoad(app.db);
272 const j = load.get(getUserByName(app.db, "juniper")!.id) ?? 0;
273 const s = load.get(getUserByName(app.db, "sentinel")!.id) ?? 0;
274 expect(j + s).toBeGreaterThanOrEqual(SWEEP_SENDS);
275 expect(Math.abs(j - s)).toBeLessThanOrEqual(2);
276 const panel = String(flowPanel(app, { kind: "owner" }, new URL("http://localhost/boards"), "/boards"));
277 expect(panel).toContain("data-reviewer-load");
278 expect(flowLines(app.db).join("\n")).toMatch(new RegExp(`Reviews in flight:.*juniper ${j}`));
279 expect(panel).toContain(`data-reviewer="juniper"`);
266280 }, 120_000);
267281 });
268282

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs