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
scout/forge:scout/4486-reviews-go-to-the-least-busy-reviewer-on → main 3 commits fork 6 threads · 6 unresolved
README.md +11 −4
| @@ -1167,10 +1167,17 @@ the agent picks it up in the background, resuming its session. A failed check re | ||
| 1167 | 1167 | times before a person must speak. |
| 1168 | 1168 | |
| 1169 | 1169 | **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. | |
| 1174 | 1181 | |
| 1175 | 1182 | **Three rounds, then a person.** When the crew reviewer has asked for |
| 1176 | 1183 | 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 => | ||
| 60 | 60 | * change to `src/web/` that is not security's goes to a reviewer on the |
| 61 | 61 | * design team (`design`, user ids) when the crew has one, and its brief |
| 62 | 62 | * 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. | |
| 63 | 68 | */ |
| 64 | 69 | export function pickReviewer( |
| 65 | 70 | reviewers: readonly Agent[], |
| 66 | 71 | paths: readonly string[], |
| 67 | 72 | design: readonly string[] = [], |
| 73 | load: ReadonlyMap<string, number> = new Map(), | |
| 68 | 74 | ): 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); | |
| 73 | 79 | const security = reviewers.filter(watchesSecurity); |
| 74 | 80 | 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); | |
| 77 | 90 | } |
| 78 | 91 | |
| 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 }[] { | |
| 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 | ||
| 79 | 108 | /** The crew's reviewers on a repository. */ |
| 80 | 109 | export const reviewersOf = (db: Database, repoId: string): Agent[] => |
| 81 | 110 | reviewersForRepos(db, [repoId]).get(repoId) ?? []; |
| @@ -90,6 +119,9 @@ export function greenHead(db: Database, pull: Pull): boolean { | ||
| 90 | 119 | return checks.length > 0 && checks.every((c) => c.state === "ok"); |
| 91 | 120 | } |
| 92 | 121 | |
| 122 | /** Review runs a preferred design reviewer may have in flight before another takes the pull. */ | |
| 123 | const REVIEW_IN_FLIGHT_MAX = 2; | |
| 124 | ||
| 93 | 125 | /** How long a review may take from being queued before it is sent again. */ |
| 94 | 126 | export const REVIEW_WAIT_MS = 20 * 60_000; |
| 95 | 127 | /** How long a green head waits for a verdict at most, however the attempts went. */ |
| @@ -431,6 +463,7 @@ export async function sendToReview( | ||
| 431 | 463 | others.length > 0 ? others : reviewers, |
| 432 | 464 | diff.files.map((f) => f.path), |
| 433 | 465 | getTeam(app.db, "design")?.members, |
| 466 | reviewLoad(app.db), | |
| 434 | 467 | ); |
| 435 | 468 | if (reviewer === undefined) return "wait"; |
| 436 | 469 | if (queueAgentRun(app, repo, issue, reviewer, "review") === undefined) |
src/tui/screens/flow.ts +7 −1
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | /** |
| 2 | 2 | * 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 | |
| 4 | 4 | * stage of what left it in the last hour and in 24 hours — the numbers of |
| 5 | 5 | * `flow/pipeline.ts` and `flow/throughput.ts`, the same the page and the |
| 6 | 6 | * MCP `flow` tool read. Under them, each repository's merge queue (#2036): |
| @@ -14,6 +14,7 @@ | ||
| 14 | 14 | */ |
| 15 | 15 | |
| 16 | 16 | import type { Database } from "bun:sqlite"; |
| 17 | import { reviewLoadRows } from "../../crew/review.ts"; | |
| 17 | 18 | import { HOLDS } from "../../crew/held.ts"; |
| 18 | 19 | import type { HeldRow } from "../../flow/held.ts"; |
| 19 | 20 | import { conflictedPulls, conflictedSays } from "../../flow/conflicted.ts"; |
| @@ -57,6 +58,11 @@ export function flowLines( | ||
| 57 | 58 | "", |
| 58 | 59 | ...wrap(throughputSays(flow), inner), |
| 59 | 60 | "", |
| 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 | "", | |
| 60 | 66 | `${pad("Out", 12)} ${pad("last hour", 9, "right")} ${pad("24 h", 5, "right")}`, |
| 61 | 67 | ...flow.stages.map(stageOut).map( |
| 62 | 68 | (s) => |
src/web/pages/flow-panel.ts +12
| @@ -35,6 +35,7 @@ import { readHeld } from "../../flow/held.ts"; | ||
| 35 | 35 | import type { App } from "../../app.ts"; |
| 36 | 36 | import { html, type Html } from "../html.ts"; |
| 37 | 37 | import { heldCard } from "./boards-held.ts"; |
| 38 | import { reviewLoadRows } from "../../crew/review.ts"; | |
| 38 | 39 | import { badge, card } from "../ui.ts"; |
| 39 | 40 | |
| 40 | 41 | /** 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 | ||
| 148 | 149 | ${STAGE_LABEL[s.key]} |
| 149 | 150 | ${s === worst ? badge("bottleneck", { tone: "danger" }) : null} |
| 150 | 151 | <div class="muted small">${STAGE_HOLDS[s.key]}</div> |
| 152 | ${s.key === "review" ? reviewerLoad(app) : null} | |
| 151 | 153 | </th> |
| 152 | 154 | <td class="mono">${String(s.waiting)}</td> |
| 153 | 155 | <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 | ||
| 166 | 168 | ${listed === null || shown === undefined ? null : outList(shown, listed.hour, now)}`; |
| 167 | 169 | } |
| 168 | 170 | |
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); | |
|
||
| 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 | ||
| 169 | 181 | /** 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/. |
||
| 170 | 182 | function queueCard(rows: readonly QueueRow[]): Html { |
| 171 | 183 | 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"; | ||
| 22 | 22 | import { createUser, getUserByName, type User } from "../src/core/users.ts"; |
| 23 | 23 | import { |
| 24 | 24 | pickReviewer, |
| 25 | reviewLoad, | |
| 25 | 26 | REVIEW_LAPSE_MS, |
| 26 | 27 | REVIEW_WAIT_MS, |
| 27 | 28 | reviewStage, |
| @@ -31,6 +32,8 @@ import { | ||
| 31 | 32 | touchesSecurity, |
| 32 | 33 | watchesSecurity, |
| 33 | 34 | } from "../src/crew/review.ts"; |
| 35 | import { flowPanel } from "../src/web/pages/flow-panel.ts"; | |
| 36 | import { flowLines } from "../src/tui/screens/flow.ts"; | |
| 34 | 37 | import { settleReview } from "../src/crew/runner.ts"; |
| 35 | 38 | |
| 36 | 39 | 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", () => { | ||
| 263 | 266 | expect(reviewer(pulls[SWEEP_SENDS - 1]!)).toHaveLength(1); |
| 264 | 267 | expect(reviewer(pulls[SWEEP_SENDS]!)).toEqual([]); |
| 265 | 268 | 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"`); | |
| 266 | 280 | }, 120_000); |
| 267 | 281 | }); |
| 268 | 282 |
Declare REVIEW_IN_FLIGHT_MAX above pickReviewer, next to the other REVIEW_* constants, so it reads before use.