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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/15164-a-stuck-flow-alarm-names-the-one-action → main 6 commits fork 2 threads · 2 unresolved
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 { | ||
| 25 | 25 | /** Set when the access wall holds it: a person must decide, in plain words (#7847). */ |
| 26 | 26 | readonly wall?: readonly string[]; |
| 27 | 27 | readonly says: string; |
| 28 | /** The one action that unblocks it, as a link: set only when fired. */ | |
| 29 | readonly action?: StuckAction; | |
| 28 | 30 | } |
| 29 | 31 | |
| 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 | ||
| 30 | 62 | export interface StuckScope { |
| 31 | 63 | /** Leave out private repositories. */ |
| 32 | 64 | readonly publicOnly?: boolean; |
| @@ -141,6 +173,7 @@ export function alarmStuck(from: App | Database, now: Date, scope: StuckScope = | ||
| 141 | 173 | number, |
| 142 | 174 | wall, |
| 143 | 175 | says: `${repo}#${number} is approved and waits for a person to merge it.`, |
| 176 | action: stuckAction(repo, number, "wall"), | |
| 144 | 177 | }; |
| 145 | 178 | return { |
| 146 | 179 | fired: true, |
| @@ -148,5 +181,6 @@ export function alarmStuck(from: App | Database, now: Date, scope: StuckScope = | ||
| 148 | 181 | repo, |
| 149 | 182 | number, |
| 150 | 183 | 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), | |
| 151 | 185 | }; |
| 152 | 186 | } |
src/flow/alarms.ts +3 −1
| @@ -32,6 +32,8 @@ export interface FiredAlarm { | ||
| 32 | 32 | readonly since: string; |
| 33 | 33 | /** A same-origin path to the item the alarm names. */ |
| 34 | 34 | readonly href: string; |
| 35 | /** The label of the one action that unblocks it, when the alarm names one. */ | |
| 36 | readonly action?: string; | |
| 35 | 37 | } |
| 36 | 38 | |
| 37 | 39 | function redMainHref(db: Database): string { |
| @@ -68,7 +70,7 @@ export function firedAlarms( | ||
| 68 | 70 | if (red.fired) out.push({ key: "red_main", says: red.says, since: red.since!, href: redMainHref(db) }); |
| 69 | 71 | const stuck = alarmStuck(db, now, opts.publicOnly ? { publicOnly: true } : {}); |
| 70 | 72 | 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 }); | |
| 72 | 74 | } |
| 73 | 75 | if (!opts.publicOnly) { |
| 74 | 76 | const silent = alarmSilent(db, now); |
src/tui/forge.ts +2
| @@ -8,6 +8,7 @@ | ||
| 8 | 8 | * to see something the web would have hidden. |
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | import { publicOrigin } from "../core/public_origin.ts"; | |
| 11 | 12 | import { nearPages } from "../web/near_pages.ts"; |
| 12 | 13 | import type { App as Forge } from "../app.ts"; |
| 13 | 14 | import { search } from "../actions/search.ts"; |
| @@ -566,6 +567,7 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] { | ||
| 566 | 567 | keeper, |
| 567 | 568 | session.app.config.dataDir, |
| 568 | 569 | 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}`), | |
| 569 | 571 | ), keeper.ask && user ? { ask: keeper.ask, answer: () => answerKeeper(session.app, keeper.ask!.id, user.id) } : undefined, |
| 570 | 572 | mayDrift(session) |
| 571 | 573 | ? { 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( | ||
| 127 | 127 | dataDir: string | null = null, |
| 128 | 128 | /** The release tick's heartbeat line, an owner's only (#11507). */ |
| 129 | 129 | heartbeat?: string, |
| 130 | /** The forge's public origin: a link in a terminal is clickable only when it is whole. */ | |
| 131 | origin = "", | |
| 130 | 132 | ): string[] { |
| 131 | 133 | const stages = readPipeline(db, now); |
| 132 | 134 | const flow = readThroughput(db, stages.map((s) => s.key), now); |
| @@ -160,7 +162,7 @@ export function flowLines( | ||
| 160 | 162 | ...(agent === undefined ? clogLines(readClog(db, now), now.getTime()).flatMap((l) => wrap(l, inner)) : []), |
| 161 | 163 | ...(agent === undefined ? clogViewLines(readClogView(db, now), inner, wrap) : []), |
| 162 | 164 | ...(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)), | |
| 164 | 166 | "", |
| 165 | 167 | ...wrap(parkedSays(fig.parked), inner), |
| 166 | 168 | "", |
src/web/studio/alarm_lines.ts +3 −1
| @@ -31,6 +31,8 @@ export function cachedAlarms(db: Database, now: Date, ceilingUsd: number | null, | ||
| 31 | 31 | export function alarmLines(alarms: readonly FiredAlarm[]): Html { |
| 32 | 32 | if (alarms.length === 0) return html``; |
| 33 | 33 | 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>`)} | |
| 35 | 37 | </div>`; |
| 36 | 38 | } |
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 | }); |
new above
offline
action label is carried but no renderer reads it (alarm_lines.ts, tui flow.ts). Render it.