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

A stuck-flow alarm names the one action that unblocks it, as a link the owner taps #15179

Merged opened this

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

Merged

scout/forge:scout/15164-a-stuck-flow-alarm-names-the-one-action → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/15164-a-stuck-flow-alarm-names-the-one-action was merged into main as 75bba3e.

Review

Sign in to review this change.
7 files changed +161 −3
docs/features/flow-stuck.md added +20
@@ -0,0 +1,20 @@
1 ---
2 topic: Ship and undo
3 row: Stuck pull: the flow alarm names the one action that unblocks it
4 ---
5 # Stuck pull: the one action
6
7 When an approved, unheld pull has had no event for 30 minutes, the flow alarm
8 names it and the one action that unblocks it, as a link:
9
10 | Stage | Label | Opens |
11 |---|---|---|
12 | The access wall holds it | Allow or send back | the pull |
13 | Last event a red check | Open the red check | that check's run page |
14 | Last event a green check | Merge it | the pull |
15 | Anything else (a run, a push, a review, a release) | Open the pull | the pull |
16
17 The label is the link text on `/flow` and `/boards` (after the sentence), and
18 the terminal flow screen prints `label: link` after the sentence, the link whole with the forge's origin so it can be clicked. Every path
19 is a page the viewer can already read; whether they may merge is decided there.
20 Code: `src/flow/alarm_stuck.ts`; test: `test/flow-alarm-stuck-action.test.ts`.
src/flow/alarm_stuck.ts +34
@@ -25,8 +25,40 @@ export interface StuckAlarm {
2525 /** Set when the access wall holds it: a person must decide, in plain words (#7847). */
2626 readonly wall?: readonly string[];
2727 readonly says: string;
28 /** The one action that unblocks it, as a link: set only when fired. */
29 readonly action?: StuckAction;
2830 }
2931
32 /** A label the card shows and the pull page path it opens; the page itself checks who may merge. */
33 export interface StuckAction {
34 readonly label: string;
35 readonly path: string;
36 }
37
38 /** Where a stuck pull stands, which decides the one action. */
39 export type StuckStage = "wall" | "red" | "green" | "other";
40
41 /**
42 * The action per stage: the wall waits for a decision, a red check for its log, a green one for
43 * the merge; anything else only for a look at the pull.
44 */
45 export function stuckAction(repo: string, number: number, stage: StuckStage, runId?: string): StuckAction {
46 const path = `/${repo}/pulls/${number}`;
47 if (stage === "wall") return { label: "Allow or send back", path };
48 if (stage === "red") return { label: "Open the red check", path: runId === undefined ? path : `/${repo}/runs/${runId}` };
49 if (stage === "green") return { label: "Merge it", path };
50 return { label: "Open the pull", path };
51 }
52
53 const stageOf = (what: string): StuckStage => (what === "a red check" ? "red" : what === "a green check" ? "green" : "other");
54
55 const redRunId = (db: Database, pullId: string): string | undefined =>
56 db
57 .query<{ id: string }, [string]>(
58 "SELECT id FROM run WHERE issue_id = ?1 AND kind = 'check' ORDER BY COALESCE(finished_at, started_at, created_at) DESC, id DESC LIMIT 1",
59 )
60 .get(pullId)?.id;
61
3062 export interface StuckScope {
3163 /** Leave out private repositories. */
3264 readonly publicOnly?: boolean;
@@ -141,6 +173,7 @@ export function alarmStuck(from: App | Database, now: Date, scope: StuckScope =
141173 number,
142174 wall,
143175 says: `${repo}#${number} is approved and waits for a person to merge it.`,
176 action: stuckAction(repo, number, "wall"),
144177 };
145178 return {
146179 fired: true,
@@ -148,5 +181,6 @@ export function alarmStuck(from: App | Database, now: Date, scope: StuckScope =
148181 repo,
149182 number,
150183 says: `${repo}#${number} has sat approved for ${sat(now.getTime() - Date.parse(last.at))}; its last event was ${last.what} at ${hhmm}.`,
184 action: stuckAction(repo, number, stageOf(last.what), last.what === "a red check" ? redRunId(db, oldest.id) : undefined),
151185 };
152186 }
src/flow/alarms.ts +3 −1
@@ -32,6 +32,8 @@ export interface FiredAlarm {
3232 readonly since: string;
3333 /** A same-origin path to the item the alarm names. */
3434 readonly href: string;
35 /** The label of the one action that unblocks it, when the alarm names one. */
36 readonly action?: string;
3537 }
3638
3739 function redMainHref(db: Database): string {
@@ -68,7 +70,7 @@ export function firedAlarms(
6870 if (red.fired) out.push({ key: "red_main", says: red.says, since: red.since!, href: redMainHref(db) });
6971 const stuck = alarmStuck(db, now, opts.publicOnly ? { publicOnly: true } : {});
7072 if (stuck.fired) {
71 out.push({ key: "stuck", says: stuck.says, since: stuck.since!, href: `/${stuck.repo}/pulls/${stuck.number}` });
73 out.push({ key: "stuck", says: stuck.says, since: stuck.since!, href: stuck.action!.path, action: stuck.action!.label });
7274 }

action label is carried but no renderer reads it (alarm_lines.ts, tui flow.ts). Render it.

7375 if (!opts.publicOnly) {
7476 const silent = alarmSilent(db, now);
src/tui/forge.ts +2
@@ -8,6 +8,7 @@
88 * to see something the web would have hidden.
99 */
1010
11 import { publicOrigin } from "../core/public_origin.ts";
1112 import { nearPages } from "../web/near_pages.ts";
1213 import type { App as Forge } from "../app.ts";
1314 import { search } from "../actions/search.ts";
@@ -566,6 +567,7 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
566567 keeper,
567568 session.app.config.dataDir,
568569 flowReader.kind === "owner" ? beatLine(lastBeat(session.db), new Date()) : undefined,
570 publicOrigin(session.app.config.url, `http://${session.app.config.host ?? "localhost"}:${session.app.config.port ?? 3000}`),
569571 ), keeper.ask && user ? { ask: keeper.ask, answer: () => answerKeeper(session.app, keeper.ask!.id, user.id) } : undefined,
570572 mayDrift(session)
571573 ? { read: async () => readHandoverLists(session.db, await readDrifts(session.app), Date.now()), update: (n) => askUpdate(session, n) }
src/tui/screens/flow.ts +3 −1
@@ -127,6 +127,8 @@ export function flowLines(
127127 dataDir: string | null = null,
128128 /** The release tick's heartbeat line, an owner's only (#11507). */
129129 heartbeat?: string,
130 /** The forge's public origin: a link in a terminal is clickable only when it is whole. */
131 origin = "",
130132 ): string[] {
131133 const stages = readPipeline(db, now);
132134 const flow = readThroughput(db, stages.map((s) => s.key), now);
@@ -160,7 +162,7 @@ export function flowLines(
160162 ...(agent === undefined ? clogLines(readClog(db, now), now.getTime()).flatMap((l) => wrap(l, inner)) : []),
161163 ...(agent === undefined ? clogViewLines(readClogView(db, now), inner, wrap) : []),
162164 ...(agent === undefined ? cpuStopLines(cpuStops(db, now).stopped, cpuClosedPulls(db, now), inner) : []),
163 ...firedAlarms(db, now, { publicOnly: agent !== undefined, ceilingUsd, dataDir }).flatMap((a) => wrap(a.says, inner)),
165 ...firedAlarms(db, now, { publicOnly: agent !== undefined, ceilingUsd, dataDir }).flatMap((a) => wrap(a.action === undefined ? a.says : `${a.says} ${a.action}: ${origin}${a.href}`, inner)),
164166 "",
165167 ...wrap(parkedSays(fig.parked), inner),
166168 "",
src/web/studio/alarm_lines.ts +3 −1
@@ -31,6 +31,8 @@ export function cachedAlarms(db: Database, now: Date, ceilingUsd: number | null,
3131 export function alarmLines(alarms: readonly FiredAlarm[]): Html {
3232 if (alarms.length === 0) return html``;
3333 return html`<div class="stack">
34 ${alarms.map((a) => html`<p class="small"><a href="${a.href}">${a.says}</a></p>`)}
34 ${alarms.map((a) => a.action === undefined
35 ? html`<p class="small"><a href="${a.href}">${a.says}</a></p>`
36 : html`<p class="small">${a.says} <a href="${a.href}">${a.action}</a></p>`)}
3537 </div>`;
3638 }
test/flow-alarm-stuck-action.test.ts added +96
@@ -0,0 +1,96 @@
1 /** A stuck-pull alarm names the one action that unblocks it, as a path to the pull (#15164). */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { createUser } from "../src/core/users.ts";
8 import { alarmStuck, stuckAction } from "../src/flow/alarm_stuck.ts";
9 import { alarmLines } from "../src/web/studio/alarm_lines.ts";
10 import { firedAlarms } from "../src/flow/alarms.ts";
11 import { flowLines } from "../src/tui/screens/flow.ts";
12
13 const NOW = new Date("2026-10-26T12:00:00.000Z");
14 const ago = (m: number): string => new Date(NOW.getTime() - m * 60_000).toISOString();
15 let dir: string;
16 let app: App;
17 let uid: string;
18
19 beforeAll(async () => {
20 dir = await mkdtemp(join(tmpdir(), "alarm-stuck-action-"));
21 app = createApp({ dataDir: dir, port: 0 });
22 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
23 if (!u.ok) throw new Error(u.error);
24 uid = u.value.id;
25 app.db.run("INSERT INTO repo (id, owner_id, name, visibility, autonomy) VALUES ('r', ?1, 'r', 'public', 'auto')", [uid]);
26 });
27 afterAll(async () => {
28 app.close?.();
29 await rm(dir, { recursive: true, force: true });
30 });
31
32 function stuck(check: "failed" | "ok" | "running", wall = false): void {
33 for (const t of ["decision", "run", "review", "pull"]) app.db.run(`DELETE FROM ${t}`);
34 app.db.run("DELETE FROM issue");
35 app.db.run("INSERT INTO issue (id, repo_id, number, kind, title, author_id, state, created_at) VALUES ('p', 'r', 7, 'pull', 't', ?1, 'open', ?2)", [uid, ago(9000)]);
36 app.db.run("INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid) VALUES ('p', 'main', 'b', '', 'h')");
37 app.db.run("INSERT INTO review (id, issue_id, author_id, state, commit_oid, created_at) VALUES ('rv', 'p', ?1, 'approved', 'h', ?2)", [uid, ago(900)]);
38 app.db.run("INSERT INTO run (id, repo_id, kind, issue_id, state, commit_oid, created_at, finished_at) VALUES ('run', 'r', 'check', 'p', ?1, 'h', ?2, ?2)", [check, ago(60)]);
39 if (wall)
40 app.db.run(
41 "INSERT INTO decision (id, kind, repo_id, issue_id, state, answer, p, by, ms) VALUES ('d', 'land', 'r', 'p', ?1, 'wall', 1, 'wall', 0)",
42 [JSON.stringify({ head: "h", plain: ["new access"] })],
43 );
44 }
45
46 test("a green quiet pull is unblocked by merging it", () => {
47 stuck("ok");
48 expect(alarmStuck(app, NOW).action).toEqual({ label: "Merge it", path: "/alice/r/pulls/7" });
49 });
50
51 test("a red check sends the owner to the check", () => {
52 stuck("failed");
53 expect(alarmStuck(app, NOW).action).toEqual({ label: "Open the red check", path: "/alice/r/runs/run" });
54 });
55
56 test("a check still running, or a bare push, only opens the pull", () => {
57 stuck("running");
58 expect(alarmStuck(app, NOW).action).toEqual({ label: "Open the pull", path: "/alice/r/pulls/7" });
59 stuck("ok");
60 app.db.run("DELETE FROM run");
61 const a = alarmStuck(app, NOW);
62 expect(a.action?.label).toBe("Open the pull");
63 });
64
65 test("the rendered alarm line shows the label as the link", () => {
66 stuck("ok");
67 const fired = firedAlarms(app.db, NOW, { dataDir: null }).filter((a) => a.key === "stuck");
68 const out = String(alarmLines(fired));
69 expect(out).toContain('<a href="/alice/r/pulls/7">Merge it</a>');
70 });
71
72 test("the access wall asks for a decision", () => {
73 stuck("ok", true);
74 expect(alarmStuck(app, NOW).action).toEqual({ label: "Allow or send back", path: "/alice/r/pulls/7" });
75 });
76
77 test("an unfired alarm offers no action; the feed card carries label and href, public readers too", () => {
78 stuck("ok");
79 const fired = firedAlarms(app.db, NOW, { dataDir: null, publicOnly: true }).find((a) => a.key === "stuck");
80 expect(fired?.href).toBe("/alice/r/pulls/7");
81 expect(fired?.action).toBe("Merge it");
82 app.db.run("DELETE FROM review");
83 expect(alarmStuck(app, NOW).action).toBeUndefined();
84 expect(stuckAction("a/b", 1, "wall").path).toBe("/a/b/pulls/1");
85 });
86
87 test("a red check with no run to open falls back to the pull path", () => {
88 expect(stuckAction("alice/r", 7, "red")).toEqual({ label: "Open the red check", path: "/alice/r/pulls/7" });
89 expect(stuckAction("alice/r", 7, "red", "run")).toEqual({ label: "Open the red check", path: "/alice/r/runs/run" });
90 });
91
92 test("the terminal prints the label and the whole link, origin first", () => {
93 stuck("ok");
94 const out = flowLines(app.db, NOW, [], undefined, [], null, undefined, undefined, null, undefined, "https://forge.example").join(" ").replace(/\s+/g, " ");
95 expect(out).toContain("Merge it: https://forge.example/alice/r/pulls/7");
96 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs