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

Each flow lane shows how long its cards wait: now and typical, and the slowest lane is named #14886

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/14882-each-flow-lane-shows-how-long-its-cards → main 13 commits fork 11 threads · 11 unresolved

  • Merged. scout/14882-each-flow-lane-shows-how-long-its-cards was merged into main as bc747ab.

Review

Sign in to review this change.
13 files changed +561 −8
docs/MCP.md +1 −1
@@ -409,7 +409,7 @@ answers
409409 | `ui://forge/asked` | `asked` | What people asked the crew for and where each ask stands. |
410410 | `ui://forge/explore` | `explore` | Apps, people and forges ranked, at most 20: name, kind, the numbers (and likes or ship time when sorted by them), linked; only what you may see. With `kind: tree`: upstream, this and fork rows, each with how it follows and linked to its repository. |
411411 | `ui://forge/issue` | `issue` | One issue: title, state, assignee, labels, what it waits for. |
412 | `ui://forge/flow` | `flow` | The pipeline: per stage counts, oldest waiting, the bottleneck. |
412 | `ui://forge/flow` | `flow` | The pipeline: per stage counts, oldest waiting, the bottleneck. `{ kind: "lanes" }` (a forge admin who is a person): each home lane's now and typical seconds and the slowest lane. |
413413 | `ui://forge/scorecard` | `scorecard` | The crew's scorecard, one row per agent: landed and red rate all time, then the week (forge admin). |
414414 | `ui://forge/crew` | `now`, `crew` | `now`: what the crew is doing right now, with Stop buttons. `crew` (listing): one row per seat, who fills it and what runs and waits, or what it costs to leave it empty; linked to Settings › Crew. |
415415 | `ui://forge/health` | `health` | Green or red with the version, then one row per cause: draining, a blocked rollout, degraded lanes, incidents, apps (an admin sees all; a stranger only the verdict). Its answer splits causes into `broken` (act now; any makes `ok` false) and `todo` (would like done; `ok` stays true). |
docs/design/areas/home-flow.md +1
@@ -13,6 +13,7 @@
1313 - `.lane` — one lane, a live region of its own (`data-live`, `data-live-src="/live/lane?s=<lane>"`) so one event redraws one lane. Its `data-tone` (quiet, flowing, waiting, stuck) draws the top edge; `data-count` is the number in the head.
1414 - `.lane-head`, `.lane-name`, `.lane-name-link`, `.lane-count` — the lane's name (a link to the full list it counts) and its count.
1515 - `.lane-health`, `.lane-state` — the lane's own health, a dot and a word, then a full sentence saying what it waits on and how old its oldest item is.
16 - `.lane-times` — one line under the health, "now 18m · typical 9m" (the median age of the cards the viewer can see, and the median time cards spent in it over 24 hours; a viewer who is not a forge admin sees "typical —"). It is one line tall, empty where there is nothing to say. `.lane-bottleneck` — the word "Slowest" at `--fg` weight in the head of the lane whose now median is furthest above its typical (`data-bottleneck` on the lane); at most one lane wears it. A tile's clock is its age in the lane.
1617 - `.lane-list` — the lane's tiles, in the order the next worker takes them.
1718 - `.lane-more`, `.lane-more-link`, `.lane-more-lg`, `.lane-more-md`, `.lane-more-sm`, `.lane-toggle`, `.lane-all` — what lies past the tiles. On a desk "N more" opens the table filtered to the lane. On a phone a lane shows its first four tiles (two lines each: the title, then the app, who has it and where it is, with the clock beside the title); with script "Show all N" opens the lane in place up to twelve tiles, then "All N in the table", and the lane keeps `data-open` through every redraw; without script "N more" is the table link.
1819 - `.tile`, `.tile-link`, `.tile-top`, `.tile-app`, `.tile-no`, `.tile-clock`, `.tile-title`, `.tile-hint`, `.tile-who` — one change: the app and number, how long it has been in this lane, its title in plain words, who has it and one sentence of where it is. `data-key` is stable across lanes, so the page glides a tile from the lane it left to the lane it reached (`home_flow_client.ts`); `data-state` is `waiting`, `active` (a pulse on the clock) or `done` (live).
docs/features/lane-times.md added +15
@@ -0,0 +1,15 @@
1 ---
2 topic: Tell the crew
3 row: Lane times
4 ---
5 # Lane times
6
7 Each home flow lane says how long its cards wait: `now 18m · typical 9m`. Now is the median age of the cards the viewer can see in the lane; typical is the median time cards spent in it over the last 24 hours (`src/flow/lane_times.ts`, read in the worker with the picture). The lane furthest above its typical wears the word **Slowest**. Asked has no typical. A tile's clock is only its age in the lane.
8
9 Who sees what: now is drawn from the viewer's own cards (`viewFor`), so a private repository's cards never count for someone who cannot read it. Typical is read across every repository, so it, and the Slowest mark that needs it, are shown only to a forge admin who is a person; anyone else sees now alone.
10
11 Terminal: the Flow screen (`src/tui/screens/lane_times.ts`, from the Flow command in `src/tui/forge.ts`) ends with a Lane times block, one line a lane with now, the oldest card, typical and p90, the slowest marked; a forge admin who is a person alone, as on the page. It reads the kept picture and never waits, so the command stays synchronous; before the first reading it says reading….
outdated

Both doors: the terminal must show lane times too; "none" is a change request. Add a src/tui Flow screen section (admin person only) and update this line.

12
13 MCP: `flow {kind: "lanes"}` (a forge admin who is a person) answers `{ slowest, lanes: [{ lane, cards, nowSeconds, oldestSeconds, typicalSeconds, p90Seconds }] }`. `now` is unchanged: runs only.
14
15 Test: `test/lane-times.test.ts` (page, MCP and terminal).
src/flow/lane_times.ts added +238
@@ -0,0 +1,238 @@
1 /**
2 * How long things wait in each lane, the number that names the bottleneck. Two times a lane
3 * wears: _now_, the median age of the cards in it with the oldest card's age, and _typical_, the
4 * median time cards spent in it over the last 24 hours with the p90. The lane whose now median is
5 * furthest above its typical one is the bottleneck.
6 *
7 * Typical is read from the records already kept, in the worker with the picture (`readTypicals`,
8 * the slow part of `lanes_read.ts`), never on a request: building and checks are a run's created →
9 * finished, review is a pull's last green check → its first verdict, landing is its last approval →
10 * merged, live is merged → the first production deploy serving. Now is plain arithmetic over the
11 * cards a viewer sees (`nowTimes`), so it is never older than the page. Asked has no typical:
12 * what you asked waits for as long as you leave it.
13 */
14
15 import type { Database } from "bun:sqlite";
16 import type { LaneKey } from "./lanes_read.ts";
17
18 /** Rows read per lane; the newest first, so a busy day is the day's latest. */
19 const SAMPLE = 500;
20 /** Fewer finished cards than this say nothing typical. */
21 export const MIN_TYPICAL = 3;
22 /**
23 * A typical shorter than this is counted as this, so a lane that is always instant is not always
24 * "late".
25 */
26 const FLOOR_MS = 60_000;
27
28 export interface Typical {
29 readonly medianMs: number;
30 readonly p90Ms: number;
31 /** Cards it was read over. */
32 readonly n: number;
33 }
34 export type Typicals = Readonly<Record<LaneKey, Typical | null>>;
35
36 export interface NowTimes {
37 readonly medianMs: number;
38 readonly oldestMs: number;
39 readonly n: number;
40 }
41 export type Nows = Readonly<Record<LaneKey, NowTimes | null>>;
42
43 /** The value at fraction `q` of an ascending list, by nearest rank. */
44 function pick(sorted: readonly number[], q: number): number {
45 return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))]!;
46 }
47
48 /** The median and p90 of some durations, or null when there are none. */
49 export function typicalOf(durations: readonly number[]): Typical | null {
50 const ms = durations.filter((d) => Number.isFinite(d)).map((d) => Math.max(0, d)).sort((a, b) => a - b);
51 if (ms.length === 0) return null;
52 const mid = ms.length >> 1;
53 const medianMs = ms.length % 2 ? ms[mid]! : (ms[mid - 1]! + ms[mid]!) / 2;
54 return { medianMs, p90Ms: pick(ms, 0.9), n: ms.length };
55 }
56
57 const MS = "* 86400000.0";
58
59 const col = (db: Database, sql: string, from: string): number[] =>
60 db.query<{ ms: number | null }, [string, number]>(sql).all(from, SAMPLE).flatMap((r) => (r.ms === null ? [] : [Math.round(r.ms / 1000) * 1000]));
61
62 /** Runs of one kind that finished in the last day: created → finished. */
63 function runMs(db: Database, kind: "agent" | "check", from: string): number[] {
64 const reason = kind === "agent" ? "AND reason != 'review'" : "";
65 return col(
66 db,
67 `SELECT (julianday(finished_at) - julianday(created_at)) ${MS} AS ms
68 FROM run INDEXED BY run_finished_cov
69 WHERE kind = '${kind}' AND finished_at >= ?1 AND state IN ('ok','failed') ${reason}
70 ORDER BY finished_at DESC LIMIT ?2`,
71 from,
72 );
73 }
74
75 /** Review: a pull's last green check before its first verdict → that verdict. */
76 function reviewMs(db: Database, from: string): number[] {
77 return col(
78 db,
79 `SELECT (julianday(v.created_at) - julianday(
80 (SELECT MAX(c.finished_at) FROM run c INDEXED BY run_issue
81 WHERE c.issue_id = v.issue_id AND c.kind = 'check' AND c.state = 'ok' AND c.finished_at <= v.created_at))) ${MS} AS ms
82 FROM review v
83 WHERE v.created_at >= ?1 AND v.state != 'commented'
84 AND NOT EXISTS (SELECT 1 FROM review w WHERE w.issue_id = v.issue_id AND w.state != 'commented' AND w.created_at < v.created_at)
85 ORDER BY v.created_at DESC LIMIT ?2`,
86 from,
87 );
88 }
89
90 /** Landing: a pull's last approval → merged. */
91 function landingMs(db: Database, from: string): number[] {
92 return col(
93 db,
94 `SELECT (julianday(p.merged_at) - julianday(
95 (SELECT MAX(v.created_at) FROM review v WHERE v.issue_id = p.issue_id AND v.state = 'approved' AND v.created_at <= p.merged_at))) ${MS} AS ms
96 FROM pull p JOIN issue i ON i.id = p.issue_id JOIN repo r ON r.id = i.repo_id
97 WHERE p.merged_at >= ?1 AND p.base_branch = r.default_branch
98 ORDER BY p.merged_at DESC LIMIT ?2`,
99 from,
100 );
101 }
102
103 /** Live: merged → the first production deploy that served at or after it. */
104 function liveMs(db: Database, from: string): number[] {
105 return col(
106 db,
107 `SELECT (julianday(
108 (SELECT MIN(d.serving_at) FROM run d INDEXED BY run_deploy_serving
109 WHERE d.repo_id = r.id AND d.kind = 'deploy' AND d.env = 'production' AND d.serving_at >= p.merged_at))
110 - julianday(p.merged_at)) ${MS} AS ms
111 FROM pull p JOIN issue i ON i.id = p.issue_id JOIN repo r ON r.id = i.repo_id
112 WHERE p.merged_at >= ?1 AND p.base_branch = r.default_branch
113 ORDER BY p.merged_at DESC LIMIT ?2`,
114 from,
115 );
116 }
117
118 /**
119 * What each lane typically takes, over the last 24 hours. Read in the worker, never on a request.
120 */
121 export function readTypicals(db: Database, now: Date): Typicals {
122 const from = new Date(now.getTime() - 86_400_000).toISOString();
123 return {
124 asked: null,
125 building: typicalOf(runMs(db, "agent", from)),
126 checks: typicalOf(runMs(db, "check", from)),
127 review: typicalOf(reviewMs(db, from)),
128 landing: typicalOf(landingMs(db, from)),
129 live: typicalOf(liveMs(db, from)),
130 };
131 }
132
133 /** A card as the times see it. */
134 export interface Aged {
135 readonly since: string;
136 readonly state: "waiting" | "active" | "done";
137 }
138
139 /**
140 * How long the cards in each lane have been there. Landing counts the approved cards waiting for a
141 * merge; a merged card waiting for its deploy is Live's wait (the time Live's typical measures),
142 * and Live counts the deploys going out now, never what is done and serving.
143 */
144 export function nowTimes(lanes: Readonly<Record<LaneKey, readonly Aged[]>>, now: number): Nows {
145 const of = (cards: readonly Aged[]): NowTimes | null => {
146 const ages = cards.map((c) => Math.max(0, now - Date.parse(c.since))).filter(Number.isFinite).sort((a, b) => a - b);
147 if (ages.length === 0) return null;
148 const mid = ages.length >> 1;
149 return { medianMs: ages.length % 2 ? ages[mid]! : (ages[mid - 1]! + ages[mid]!) / 2, oldestMs: ages[ages.length - 1]!, n: ages.length };
150 };
151 const only = (cards: readonly Aged[], state: Aged["state"]) => cards.filter((c) => c.state === state);
152 return {
153 asked: of(lanes.asked),
154 building: of(lanes.building),
155 checks: of(lanes.checks),
156 review: of(lanes.review),
157 landing: of(only(lanes.landing, "waiting")),
158 live: of([...only(lanes.landing, "active"), ...only(lanes.live, "active")]),
159 };
160 }
161
162 /**
163 * The lane whose now median is furthest above its typical one: null when no lane is above its
164 * typical, or none has a typical read over enough cards.
165 */
166 export function bottleneck(nows: Nows, typicals: Typicals): LaneKey | null {
167 let worst: LaneKey | null = null;
168 let most = 1;
169 for (const k of Object.keys(nows) as LaneKey[]) {
170 const n = nows[k];
171 const t = typicals[k];
172 if (n === null || t === null || t.n < MIN_TYPICAL) continue;
173 const ratio = n.medianMs / Math.max(t.medianMs, FLOOR_MS);
174 if (ratio > most) {
175 most = ratio;
176 worst = k;
177 }
178 }
179 return worst;
180 }
181
182 /**
183 * Both times of every lane and the slowest lane: the page, the terminal and the MCP `flow` tool
184 * read this.
185 */
186 export interface LaneTimes {
187 readonly nows: Nows;
188 readonly typicals: Typicals;
189 readonly slowest: LaneKey | null;
190 }
191
192 const NO_TYPICALS: Typicals = { asked: null, building: null, checks: null, review: null, landing: null, live: null };
193
194 type Held = Readonly<Record<LaneKey, { readonly items: readonly Aged[] }>>;
195
196 /**
197 * The times over some cards. `typicals` are forge-wide (read over every repository), so a caller
198 * passes them only for a viewer who may read everything (a forge admin who is a person); anyone
199 * else passes null, and their lanes say now only, from the cards they can see, and name no slowest.
200 */
201 export function timesOf(lanes: Held, typicals: Typicals | null, now: number): LaneTimes {
202 const nows = nowTimes(
203 {
204 asked: lanes.asked.items,
205 building: lanes.building.items,
206 checks: lanes.checks.items,
207 review: lanes.review.items,
208 landing: lanes.landing.items,
209 live: lanes.live.items,
210 },
211 now,
212 );
213 const t = typicals ?? NO_TYPICALS;
214 return { nows, typicals: t, slowest: bottleneck(nows, t) };
215 }
216
217 /** "now 18m" and "typical 9m": a lane's two times, short. */
218 export function timeWords(nows: NowTimes | null, typical: Typical | null, say: (ms: number) => string): { now: string; typical: string } {
219 return {
220 now: nows === null ? "now —" : `now ${say(nows.medianMs)}`,
221 typical: typical === null ? "typical —" : `typical ${say(typical.medianMs)}`,
222 };
223 }
224
225 /**
226 * One line a lane, for the terminal: both times, the oldest card and the p90, the slowest marked.
227 */
228 export function laneLines(times: LaneTimes, names: Readonly<Record<LaneKey, string>>, say: (ms: number) => string): string[] {
229 return (Object.keys(names) as LaneKey[]).map((k) => {
230 const n = times.nows[k];
231 const t = times.typicals[k];
232 const parts = [
233 n === null ? "now —" : `now ${say(n.medianMs)} (oldest ${say(n.oldestMs)})`,
234 t === null ? "typical —" : `typical ${say(t.medianMs)} (p90 ${say(t.p90Ms)})`,
235 ];
236 return `${names[k]}: ${parts.join(" · ")}${times.slowest === k ? " · slowest" : ""}`;
237 });
238 }
src/flow/lanes.ts +8
@@ -284,6 +284,14 @@ function refresh(
284284 return p;
285285 }
286286
287 /**
288 * The last picture read, or undefined before the first: what a caller that must not wait (the
289 * terminal's Flow screen) draws from. Never reads; the keeper keeps it current.
290 */
291 export function keptPicture(db: Database): LanePicture | undefined {
292 return states.get(db)?.picture;
293 }
294
287295 /** Start reading the picture now, so the first page finds it: the forge calls this once it is listening (never `bun test`, where reads are inline). */
288296 export function warmLanes(db: Database, options: PictureOptions, now: number, owners: readonly string[] = []): void {
289297 if (!offThread(db)) return;
src/flow/lanes_read.ts +9
@@ -28,6 +28,7 @@ import { FORGE_BROKEN, firedAlarms } from "./alarms.ts";
2828 import { readBuilders, readKpis } from "./kpis.ts";
2929 import { readFigures, type Figures } from "./figures.ts";
3030 import { readLeadTime, type LeadTime } from "./lead_time.ts";
31 import { readTypicals, type Typicals } from "./lane_times.ts";
3132 import { shortTitle } from "./moving.ts";
3233 import { getUserById } from "../core/users.ts";
3334 import { reviewSetOf } from "../web/studio/review_set.ts";
@@ -133,6 +134,11 @@ export interface LanePicture {
133134 * subscription with room, nothing ready); null otherwise.
134135 */
135136 readonly idle: IdleReason | null;
137 /**
138 * What each lane typically takes over the last 24 hours (`lane_times.ts`); null until the slow
139 * part has been read.
140 */
141 readonly typicals: Typicals | null;
136142 }
137143
138144 /** The asks waiting on one person (`web/studio/review_set.ts`): the live ones, not the stale. */
@@ -629,6 +635,7 @@ export interface Slow {
629635 readonly figures: Figures;
630636 readonly asks: Readonly<Record<string, AsksWaiting>>;
631637 readonly idle: IdleReason | null;
638 readonly typicals: Typicals;
632639 }
633640
634641 /** How many of the crew's next asks the slow part keeps. */
@@ -729,6 +736,7 @@ export function readSlow(
729736 figures: readFigures(db, now, kpis),
730737 asks: asksOf(db, viewers, now),
731738 idle: idleOf(db, forge.dataDir, now),
739 typicals: readTypicals(db, now),
732740 };
733741 }
734742
@@ -804,5 +812,6 @@ export function compose(
804812 asks: slow?.asks ?? {},
805813 figures: slow?.figures ?? null,
806814 idle: slow?.idle ?? null,
815 typicals: slow?.typicals ?? null,
807816 };
808817 }
src/http/mcp/tools/flow.ts +26 −2
@@ -16,6 +16,9 @@ import { driftingPulls, readDrifts } from "../../../flow/alarm_drift.ts";
1616 import { openBugs } from "../../../flow/bugs.ts";
1717 import { cpuClosedPulls } from "../../../flow/cpu_closed.ts";
1818 import { cpuStops } from "../../../flow/cpu_stops.ts";
19 import { forgeCeiling } from "../../../flow/ceiling.ts";
20 import { LANES, lanePicture } from "../../../flow/lanes.ts";
21 import { timesOf } from "../../../flow/lane_times.ts";
1922 import { flowCached } from "../../../system/flow_cache.ts";
2023 import { scopeAllows } from "../../../core/tokens.ts";
2124 import { applyFleetOp, previewFleetOp } from "../../../actions/fleet.ts";
@@ -41,7 +44,7 @@ export const tool: Tool = {
4144 inputSchema: {
4245 type: "object",
4346 properties: {
44 kind: { type: "string", enum: ["bugs", "cpu", "drift", "growth"] },
47 kind: { type: "string", enum: ["bugs", "cpu", "drift", "growth", "lanes"] },
4548 q: { type: "string", maxLength: 500 },
4649 sort: { type: "string" },
4750 action: {},
@@ -113,13 +116,34 @@ export const tool: Tool = {
113116 const all = user.isAdmin && user.kind !== "agent" ? {} : { publicOnly: true };
114117 return good({ drifting: driftingPulls(await readDrifts(ctx.app, all), Date.now()).slice(0, 100) });
115118 }
119 if (args["kind"] === "lanes") {
120 // Forge-wide times, drawn from every repository: a forge admin who is a person, as the home
121 // draws them.
122 if (!user.isAdmin || user.kind === "agent") return bad("forbidden", "Lane times are read across every repository: a forge admin's.");
123 const at = Date.now();
124 const picture = await lanePicture(ctx.app.db, { dataDir: ctx.app.config.dataDir, ceilingUsd: forgeCeiling(ctx.app.config) }, "page", at);
125 if (picture === undefined) return good({ slowest: null, lanes: [] });
126 const times = timesOf(picture.lanes, picture.typicals, at);
127 const ms = (m: number | undefined): number | null => (m === undefined ? null : Math.round(m / 1000));
128 return good({
129 slowest: times.slowest,

Non-blocking: ms returns seconds. Rename it to secs.

130 lanes: LANES.map((lane) => ({
131 lane,
132 cards: times.nows[lane]?.n ?? 0,
133 nowSeconds: ms(times.nows[lane]?.medianMs),
134 oldestSeconds: ms(times.nows[lane]?.oldestMs),
135 typicalSeconds: ms(times.typicals[lane]?.medianMs),
136 p90Seconds: ms(times.typicals[lane]?.p90Ms),
137 })),
138 });
139 }
116140 if (args["kind"] === "cpu") {
117141 // As /flow's CPU-stop block: an admin sees every repository, anyone else public ones.
118142 const admin = user.isAdmin && user.kind !== "agent";
119143 const now = new Date();
120144 return good({ stopped: admin ? cpuStops(ctx.app.db, now).stopped : 0, closed: cpuClosedPulls(ctx.app.db, now, { publicOnly: !admin }) });
121145 }
122 if (args["kind"] !== "bugs") return bad("invalid", "kind is bugs, cpu, drift or growth");
146 if (args["kind"] !== "bugs") return bad("invalid", "kind is bugs, cpu, drift, growth or lanes");
123147 // As the terminal's bugs screen: an admin sees every repository, anyone else public ones.
124148 const all = openBugs(ctx.app.db, user.isAdmin && user.kind !== "agent" ? {} : { publicOnly: true });
125149 const now = Date.now();
src/tui/forge.ts +2 −1
@@ -93,6 +93,7 @@ import { capacityScreen, mayCapacity } from "./screens/capacity.ts";
9393 import { crawlersScreen } from "./screens/crawlers.ts";
9494 import { forgeCeiling } from "../flow/ceiling.ts";
9595 import { flowLines, flowScreen } from "./screens/flow.ts";
96 import { laneTimeLines } from "./screens/lane_times.ts";
9697 import { askUpdate, mayDrift } from "./screens/drift.ts";
9798 import { readHandoverLists } from "../flow/handover_read.ts";
9899 import { readDrifts } from "../flow/alarm_drift.ts";
@@ -568,7 +569,7 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
568569 session.app.config.dataDir,
569570 flowReader.kind === "owner" ? beatLine(lastBeat(session.db), new Date()) : undefined,
570571 publicOrigin(session.app.config.url, `http://${session.app.config.host ?? "localhost"}:${session.app.config.port ?? 3000}`),
571 ), keeper.ask && user ? { ask: keeper.ask, answer: () => answerKeeper(session.app, keeper.ask!.id, user.id) } : undefined,
572 ).concat(laneTimeLines(session.db, user)), keeper.ask && user ? { ask: keeper.ask, answer: () => answerKeeper(session.app, keeper.ask!.id, user.id) } : undefined,
572573 mayDrift(session)
573574 ? { read: async () => readHandoverLists(session.db, await readDrifts(session.app), Date.now()), update: (n) => askUpdate(session, n) }
574575 : undefined));
src/tui/screens/lane_times.ts added +20
@@ -0,0 +1,20 @@
1 /**
2 * The lane times on the terminal's Flow screen, as the home draws them (`flow/lane_times.ts`):
3 * read from the kept picture, never awaited, so the command stays synchronous. A person who is a
4 * forge admin's alone, the same gate as the page's typicals.
5 */
6 import type { Database } from "bun:sqlite";
7 import type { User } from "../../core/users.ts";
8 import { LANE_NAME, LANES, keptPicture, viewFor, type LaneKey } from "../../flow/lanes.ts";
9 import { laneLines, timesOf } from "../../flow/lane_times.ts";
10 import { span } from "../../flow/pipeline.ts";
11
12 /** The block's lines, a blank line and a heading first; none for anyone but an admin person. */
13 export function laneTimeLines(db: Database, user: User | null | undefined, now = Date.now()): string[] {
14 if (user == null || !user.isAdmin || user.kind === "agent") return [];
15 const picture = keptPicture(db);
16 if (picture === undefined) return ["", "Lane times", "reading…"];
17 const viewing = viewFor(db, user, picture);
18 const held = Object.fromEntries(LANES.map((k) => [k, { items: viewing.lanes[k].all }])) as Record<LaneKey, { items: (typeof viewing.lanes)[LaneKey]["all"] }>;
19 return ["", "Lane times", ...laneLines(timesOf(held, picture.typicals, now), LANE_NAME, span)];
20 }
src/web/pages/home_flow.ts +21 −2
@@ -23,6 +23,7 @@ import { listChildren } from "../../actions/spawn.ts";
2323 import { lastHeard, MAX_CHILDREN, QUIET_MS } from "../../spawn/heartbeat.ts";
2424 import { cellsHere, isAwakeBody } from "../../spawn/host.ts";
2525 import { forgeCeiling } from "../../flow/ceiling.ts";
26 import { timesOf, timeWords, type LaneTimes } from "../../flow/lane_times.ts";
2627 import { count, duration, money } from "../../flow/figure_format.ts";
2728 import {
2829 LANES,
@@ -38,6 +39,7 @@ import {
3839 type LaneView,
3940 type PictureOptions,
4041 type StripPart,
42 type Viewing,
4143 } from "../../flow/lanes.ts";
4244 import { span } from "../../flow/pipeline.ts";
4345 import { lastProof, proofNotice, provingSince, type Proof } from "../../release/prove.ts";
@@ -156,6 +158,15 @@ function laneHref(key: LaneKey, only: string | null): string {
156158 return `/?view=table&lane=${key}${query(only)}`;
157159 }
158160
161 /**
162 * What the viewer may read decides the times: their cards, and forge-wide typicals only for a
163 * person who is a forge admin.
164 */
165 function timesFor(viewing: Viewing, picture: LanePicture, wide: boolean, now: number): LaneTimes {
outdated

This docblock lands between laneRegion's own docblock (above) and laneRegion; move timesFor above that docblock so each function keeps its own.

166 const held = Object.fromEntries(LANES.map((k) => [k, { items: viewing.lanes[k].all }])) as Record<LaneKey, { items: Viewing["lanes"][LaneKey]["all"] }>;
167 return timesOf(held, wide ? picture.typicals : null, now);
168 }
169
159170 /**
160171 * One lane: a live region that answers for itself (`/live/lane`), so an event redraws this lane and
161172 * no other.
@@ -167,8 +178,11 @@ export function laneRegion(
167178 _admin: boolean,
168179 now: number,
169180 mine = false,
181 times?: LaneTimes,
170182 ): Html {
171183 const key = view.key;
184 const said = timeWords(times?.nows[key] ?? null, times?.typicals[key] ?? null, span);
185 const slowest = times?.slowest === key;
172186 const shown = view.items.length;
173187 const total = view.total;
174188 const href = laneHref(key, only);
@@ -183,6 +197,7 @@ export function laneRegion(
183197 data-disclose-scope
outdated

Principle 5/1: the Bottleneck badge works only as colour plus a title hover; the explanation is invisible on touch. Make the word self-explanatory ("Slowest") and drop the title.

184198 data-tone="${health.tone}"
185199 data-count="${String(view.total)}"
200 ${slowest ? html`data-bottleneck` : null}
186201 aria-label="${label}"
187202 data-live="${LANE_LIVE[key]}"
188203 data-live-src="/live/lane?s=${key}${query(only, mine)}"
@@ -190,6 +205,7 @@ export function laneRegion(
190205 >
191206 <header class="lane-head">
192207 <h2 class="lane-name"><a class="lane-name-link" href="${href}" title="${LANE_HOLDS[key]}">${LANE_NAME[key]}</a></h2>
208 ${slowest ? html`<span class="lane-bottleneck">Slowest</span>` : null}
193209 <span class="lane-count num" aria-hidden="true"
194210 >${String(view.total)}</span
195211 >
@@ -206,6 +222,7 @@ export function laneRegion(
206222 >
207223 ${health.words}
208224 </p>
225 <p class="lane-times num">${times?.nows[key] == null && times?.typicals[key] == null ? "" : html`${said.now} · ${said.typical}`}</p>
209226 ${shown === 0
210227 ? null
211228 : html`<ol class="lane-list">
@@ -340,6 +357,7 @@ export function readingLane(key: LaneKey, only: string | null): Html {
340357 <span class="lane-count num" aria-hidden="true">…</span>
341358 </header>
342359 <p class="lane-health">Reading what the forge is doing…</p>
360 <p class="lane-times num"></p>
343361 </section>`;
344362 }
345363
@@ -535,7 +553,8 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited
535553 } else if (view === "table") {
536554 main = html`${tableTools(q)}${tableRegion(tableRows(viewing, tableInput(picture, now)), q, now)}`;
537555 } else {
538 main = html`<div class="hf-lanes">${LANES.map((k) => laneRegion(viewing.lanes[k], healthOf(viewing.lanes[k], picture, now), only, user.isAdmin, now, mine))}</div>`;
556 const times = timesFor(viewing, picture, user.isAdmin && user.kind !== "agent", now);
557 main = html`<div class="hf-lanes">${LANES.map((k) => laneRegion(viewing.lanes[k], healthOf(viewing.lanes[k], picture, now), only, user.isAdmin, now, mine, times))}</div>`;
539558 }
540559 const body = html`<div class="hf" id="hf" data-view="${view}">
541560 <header class="hf-head">
@@ -630,7 +649,7 @@ export async function liveLaneFragment(ctx: Ctx): Promise<Response> {
630649 }
631650 const viewing = timePhase(ctx.request, "viewing", () => viewFor(ctx.app.db, user, picture, only, waits));
632651 const view = viewing.lanes[key];
633 const res = fragment(laneRegion(view, healthOf(view, picture, now), only, user.isAdmin, now, mine), { request: ctx.request, etag: tag });
652 const res = fragment(laneRegion(view, healthOf(view, picture, now), only, user.isAdmin, now, mine, timesFor(viewing, picture, user.isAdmin && user.kind !== "agent", now)), { request: ctx.request, etag: tag });
634653 notePhase(ctx.request, "render", performance.now() - rendering);
635654 return res;
636655 }
src/web/pages/home_flow_style.ts +2
@@ -48,6 +48,8 @@ export const homeFlowCss = /* css */ `
4848 .lane-count { font-size: 20px; font-weight: 600; line-height: 24px; letter-spacing: -0.01em; }
4949 .lane[data-count="0"] .lane-count { color: var(--faint); }
5050 .lane-health { margin: 0; padding-inline: 4px; font-size: 12.5px; line-height: 18px; color: var(--muted-fg); }
51 .lane-times { margin: 0; padding-inline: 4px; font-size: 12.5px; line-height: 18px; min-height: 18px; color: var(--muted-fg); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
outdated

Principle 3: min-height: 36px keeps two lines of space for one 18px line, empty most of the time. Use 18px, or render the line only where there is data without shifting layout.

52 .lane-bottleneck { margin-left: auto; font-size: 12.5px; font-weight: 600; color: var(--fg); }
outdated

Principle 5: --danger is a second accent colour; mark the bottleneck with --fg weight, not colour.

5153 .lane-state { display: inline-flex; align-items: center; gap: 4px; margin-right: 4px; font-weight: 600; color: var(--fg); white-space: nowrap; }
5254 .lane-list { display: flex; flex-direction: column; gap: 8px; margin: 0; padding: 0; list-style: none; }
5355
test/fork-tree-chip.test.ts +3 −2
@@ -30,8 +30,9 @@ beforeAll(async () => {
3030 const lib = must(await createRepo(app, users["ann"], { name: "lib", visibility: "public" }));
3131 must(await commitToBranch(app, users["ann"], lib, { message: "start", files: [{ path: "a.txt", content: "a\n" }] }));
3232 must(await forkRepo(app, users["bea"], lib));
33 // The fork must not follow on its own, or it would catch up as the parent moves.
34 setForkFollowMode(app.db, getRepo(app.db, "bea", "lib")!.id, "tell-me");
33 // The fork must not follow on its own, or it would catch up as the parent moves: `tell-me` still
34 // fast-forwards a fork with no work of its own, in the background, so the count raced it.
35 setForkFollowMode(app.db, getRepo(app.db, "bea", "lib")!.id, "dont-follow");
3536 }, 30_000);
3637
3738 afterAll(async () => {
test/lane-times.test.ts added +215
@@ -0,0 +1,215 @@
1 /**
2 * How long things wait in each lane (`flow/lane_times.ts`): the typical time is read from a
3 * seeded run table (and reviews, pulls, deploys), the now time from the cards, and the bottleneck
4 * is the lane whose now is furthest above its typical. The home shows them and the MCP `now` says
5 * the slowest lane.

Non-blocking: stale. The MCP now tool does not name the slowest lane; flow {kind: lanes} does.

6 */
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createToken } from "../src/core/tokens.ts";
13 import { createSession } from "../src/core/sessions.ts";
14 import { serve, type Servers } from "../src/http/server.ts";
15 import { createUser, getUserByName } from "../src/core/users.ts";
16 import { bottleneck, nowTimes, readTypicals, timesOf, typicalOf, type Typicals } from "../src/flow/lane_times.ts";
17 import { lanePicture, readLanesInline, type LaneKey } from "../src/flow/lanes.ts";
18 import { laneTimeLines } from "../src/tui/screens/lane_times.ts";
19 import { seedHomeFlow, type HomeFlowSeed } from "./helpers/home-flow-seed.ts";
20
21 const MIN = 60_000;
22 const NOW = Date.now();
23 const ago = (m: number): string => new Date(NOW - m * MIN).toISOString();
24
25 let dataDir: string;
26 let app: App;
27 let servers: Servers;
28 let seed: HomeFlowSeed;
29
30 beforeAll(async () => {
31 dataDir = await mkdtemp(join(tmpdir(), "forge-lane-times-"));
32 app = createApp({ dataDir, port: 0 });
33 seed = await seedHomeFlow(app);
34 servers = await serve(app);
35 });
36 afterAll(async () => {
37 servers.stop();
38 app.close();
39 await rm(dataDir, { recursive: true, force: true });
40 });
41
42 let n = 0;
43 function run(kind: "agent" | "check" | "deploy", created: number, finished: number, over: { issue?: string; reason?: string; env?: string; serving?: number } = {}): void {
44 app.db.run(
45 `INSERT INTO run (id, repo_id, kind, issue_id, commit_oid, state, reason, env, created_at, started_at, finished_at, serving_at)
46 VALUES (?1, ?2, ?3, ?4, 'c0ffee3', 'ok', ?5, ?6, ?7, ?7, ?8, ?9)`,
47 [`run-lt-${++n}`, seed.repos.forge.id, kind, over.issue ?? null, over.reason ?? "", over.env ?? "", ago(created), ago(finished), over.serving === undefined ? null : ago(over.serving)],
48 );
49 }
50
51 describe("typical time, from the records kept", () => {
52 test("median and p90 of some durations", () => {
53 expect(typicalOf([])).toBeNull();
54 expect(typicalOf([40, 10, 10, 10, 10])).toEqual({ medianMs: 10, p90Ms: 40, n: 5 });
55 expect(typicalOf([4, 8, 6, 2])).toEqual({ medianMs: 5, p90Ms: 8, n: 4 });
56 });
57
58 test("each lane's typical is read from a seeded table, over the last 24 hours only", () => {
59 // Nothing the seed holds may count: only these runs are in the table.
60 app.db.run("DELETE FROM run");
61 // building: created → finished, 10 10 10 10 40 minutes; a review run and an old one do not
62 // count
63 for (const m of [10, 10, 10, 10, 40]) run("agent", 100 + m, 100, { reason: "feedback" });
64 run("agent", 100 + 500, 100, { reason: "review" });
65 run("agent", 30 * 60 + 300, 30 * 60, { reason: "" });
66 // checks: 4 6 8
67 for (const m of [4, 6, 8]) run("check", 200 + m, 200);
68 // review: the last green check → the first verdict, 10 minutes
69 const pull = Object.values(seed.pulls)[0]!;
70 run("check", 126, 120, { issue: pull });
71 app.db.run("DELETE FROM review WHERE issue_id = ?1", [pull]);
72 app.db.run("INSERT INTO review (id, issue_id, author_id, state, created_at) VALUES ('rv-lt-1', ?1, ?2, 'approved', ?3)", [pull, seed.owner.id, ago(110)]);
73 // landing: approved → merged, 10 minutes; live: merged → a production deploy serving, 5 minutes
74 app.db.run("UPDATE pull SET merged_at = ?2, base_branch = 'main' WHERE issue_id = ?1", [pull, ago(100)]);
75 run("deploy", 99, 95, { env: "production", serving: 95 });
76
77 const t = readTypicals(app.db, new Date(NOW));
78 expect(t.asked).toBeNull();
79 expect(t.building).toEqual({ medianMs: 10 * MIN, p90Ms: 40 * MIN, n: 5 });
80 // 4 6 8, and the green check of the review pull, 6
81 expect(t.checks?.medianMs).toBeCloseTo(6 * MIN, -2);
82 expect(t.checks?.p90Ms).toBeCloseTo(8 * MIN, -2);
83 expect(t.checks?.n).toBe(4);
84 expect(t.review).toMatchObject({ n: 1 });
85 expect(t.review!.medianMs).toBeCloseTo(10 * MIN, -2);
86 expect(t.landing!.medianMs).toBeCloseTo(10 * MIN, -2);
87 expect(t.live!.medianMs).toBeCloseTo(5 * MIN, -2);
88 });
89 });
90
91 describe("now time, from the cards", () => {
92 const card = (m: number, state: "waiting" | "active" | "done" = "waiting") => ({ since: ago(m), state });
93 const empty: Record<LaneKey, never[]> = { asked: [], building: [], checks: [], review: [], landing: [], live: [] };
94
95 test("the median age of the cards and the oldest", () => {
96 const now = nowTimes({ ...empty, checks: [card(10), card(18), card(54)] }, NOW);
97 expect(now.checks!.medianMs).toBeCloseTo(18 * MIN, -2);
98 expect(now.checks!.oldestMs).toBeCloseTo(54 * MIN, -2);
99 expect(now.building).toBeNull();
100 });
101
102 test("a merged card waits for its deploy in Live's time, and a served one is no wait", () => {
103 const now = nowTimes({ ...empty, landing: [card(30, "waiting"), card(7, "active")], live: [card(2, "active"), card(500, "done")] }, NOW);
104 expect(now.landing!.n).toBe(1);
105 expect(now.live!.n).toBe(2);
106 expect(now.live!.oldestMs).toBeCloseTo(7 * MIN, -2);
107 });
108 });
109
110 const timesOf2 = (p: { lanes: Parameters<typeof timesOf>[0]; typicals: Typicals }, now: number) => timesOf(p.lanes, p.typicals, now);
111
112 describe("the bottleneck is the lane furthest above its typical", () => {
113 const typical = (m: number) => ({ medianMs: m * MIN, p90Ms: m * 3 * MIN, n: 10 });
114 const typicals: Typicals = { asked: null, building: typical(10), checks: typical(5), review: typical(20), landing: typical(30), live: typical(5) };
115 const card = (m: number) => ({ since: ago(m), state: "waiting" as const });
116 const lanes = (over: Partial<Record<LaneKey, { since: string; state: "waiting" }[]>>) => ({
117 lanes: { asked: { items: [card(5000)] }, building: { items: [card(9)] }, checks: { items: [card(4)] }, review: { items: [card(15)] }, landing: { items: [card(20)] }, live: { items: [] }, ...Object.fromEntries(Object.entries(over).map(([k, v]) => [k, { items: v }])) } as Record<LaneKey, { items: { since: string; state: "waiting" }[] }>,
118 typicals,
119 });
120
121 test("it moves to the lane a test slows down", () => {
122 expect(timesOf2(lanes({ checks: [card(54), card(60)] }), NOW).slowest).toBe("checks");
123 expect(timesOf2(lanes({ checks: [card(54)], building: [card(300)] }), NOW).slowest).toBe("building");
124 expect(timesOf2(lanes({ checks: [card(54)], building: [card(300)], review: [card(16 * 60)] }), NOW).slowest).toBe("review");
125 });
126
127 test("no lane above its typical, or a typical read over too few cards, names none; Asked never", () => {
128 expect(timesOf2(lanes({}), NOW).slowest).toBeNull();
129 const nows = nowTimes({ asked: [card(9999)], building: [card(900)], checks: [], review: [], landing: [], live: [] }, NOW);
130 expect(bottleneck(nows, typicals)).toBe("building");
131 expect(bottleneck(nows, { ...typicals, building: { ...typicals.building!, n: 2 } })).toBeNull();
132 });
133 });
134
135 describe("the home, the terminal and the MCP say it, to whoever may read it", () => {
136 const callFlow = async (token: string, args: object) => {
137 const call = await fetch(`${servers.url}/mcp`, {
138 method: "POST",
139 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
140 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "flow", arguments: args } }),
141 });
142 return ((await call.json()) as any).result;
143 };
144
145 test("the picture carries the typicals; a lane's header both times, a tile only its age", async () => {
146 const picture = readLanesInline(app.db, { dataDir, ceilingUsd: null }, NOW);
147 expect(picture.typicals?.building?.n).toBe(5);
148 // a check that has run for ten hours is in the lane
149 app.db.run("INSERT INTO run (id, repo_id, kind, commit_oid, state, created_at, started_at) VALUES ('run-lt-stuck', ?1, 'check', 'c0ffee4', 'running', ?2, ?2)", [seed.repos.forge.id, ago(600)]);
150 app.db.run("UPDATE issue SET title = title WHERE id = ?1", [Object.values(seed.issues)[0]!]);
151 const cookie = `forge_session=${createSession(app.db, seed.owner.id).token}`;
152 const html = await (await fetch(`${servers.url}/`, { headers: { cookie } })).text();
153 const checks = html.split('id="lane-checks"')[1]!.split("</section>")[0]!;
154 expect(checks).toMatch(/class="lane-times num">now [^<]* · typical 6m</);
155 expect(checks).not.toContain("title=\"oldest");
156 expect(html).not.toMatch(/in checks <time|asked <time/);
157 expect(html.split('id="lane-asked"')[1]!.split("</section>")[0]).toContain("typical —");
158 expect(html.match(/data-bottleneck/g)?.length ?? 0).toBeLessThanOrEqual(1);
159 expect(html).not.toContain("Bottleneck<");
160 expect(html).not.toContain("--danger");
161 });
162
163 test("a guest or a member of nothing sees no forge-wide typical and no slowest lane", async () => {
164 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "stranger", allowReserved: true, email: "[email protected]", password: "a-good-passphrase" });
165 if (!made.ok) throw new Error(made.error);
166 // the private repository's check has run for twenty hours
167 app.db.run("INSERT INTO run (id, repo_id, kind, commit_oid, state, created_at, started_at) VALUES ('run-lt-private', ?1, 'check', 'c0ffee5', 'running', ?2, ?2)", [seed.repos.glue.id, ago(1200)]);
168 const cookie = `forge_session=${createSession(app.db, made.value.id).token}`;
169 for (const headers of [{ cookie }, {}]) {
170 const html = await (await fetch(`${servers.url}/`, { headers })).text();
171 expect(html).not.toContain("data-bottleneck");
172 expect(html).not.toContain("Slowest<");
173 expect(html).not.toMatch(/typical \d/);
174 expect(html).not.toContain("20h");
175 }
176 const lane = await (await fetch(`${servers.url}/live/lane?s=checks`, { headers: { cookie } })).text();
177 expect(lane).not.toMatch(/typical \d|Slowest|20h/);
178 });
179
180 test("the MCP now answer keeps its shape: runs only", async () => {
181 const token = createToken(app.db, seed.owner.id, "t", "rw").token;
182 const call = await fetch(`${servers.url}/mcp`, {
183 method: "POST",
184 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
185 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "now", arguments: {} } }),
186 });
187 const rows = JSON.parse(((await call.json()) as any).result.content[0].text) as { why: string; who: string }[];
188 expect(rows.some((r) => r.why === "bottleneck" || r.who === "the forge")).toBe(false);
189 });
190
191 test("MCP flow {kind: lanes} is the admin's: its own fields; anyone else is refused", async () => {
192 const owner = createToken(app.db, seed.owner.id, "t2", "rw").token;
193 const res = await callFlow(owner, { kind: "lanes" });
194 const body = JSON.parse(res.content[0].text) as { slowest: string | null; lanes: { lane: string; cards: number; nowSeconds: number | null; typicalSeconds: number | null }[] };
195 expect(body.lanes.map((l) => l.lane)).toEqual(["asked", "building", "checks", "review", "landing", "live"]);
196 expect(body.slowest).toBe("checks");
197 expect(body.lanes.find((l) => l.lane === "checks")!.typicalSeconds).toBe(360);
198 const stranger = getUserByName(app.db, "stranger")!;
199 const refused = await callFlow(createToken(app.db, stranger.id, "t3", "rw").token, { kind: "lanes" });
200 expect(refused.isError).toBe(true);
201 expect(JSON.stringify(refused)).not.toContain("checks");
202 });
203
204 test("the terminal's Flow screen: one line a lane for an admin person, read without waiting; nobody else gets the block", async () => {
205 await lanePicture(app.db, { dataDir, ceilingUsd: null });
206 const lines = laneTimeLines(app.db, seed.owner, NOW);
207 expect(lines.slice(0, 2)).toEqual(["", "Lane times"]);
208 expect(lines).toHaveLength(8);
209 expect(lines.find((l) => l.startsWith("Checks: "))).toMatch(/^Checks: now \S+ \(oldest \S+\) · typical 6m \(p90 8m\) · slowest$/);
210 expect(lines.find((l) => l.startsWith("Asked: "))).toMatch(/typical —/);
211 expect(laneTimeLines(app.db, getUserByName(app.db, "stranger")!, NOW)).toEqual([]);
212 expect(laneTimeLines(app.db, { ...seed.owner, kind: "agent" }, NOW)).toEqual([]);
213 expect(laneTimeLines(app.db, null, NOW)).toEqual([]);
214 });
215 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs