The one flow

src/flow/stage.ts is a pure function from an issue's records to {stage, since, stalled, unblock, pull}. src/flow/read.ts reads those records (pulls, the checks at each head, reviews, production deploys) and serves GET /api/v1/repos/:owner/:name/flow: {open: [...], live: [...]} — every open issue plus any merged issue production has not yet served (stage land, so wait for the production deploy and redeploy production show), and what went live in the last 24 hours.

Stages: issue → pull → check → review → land → live. Stalled past: issue 24 h, pull 1 h, check 30 min, review 12 h, land 2 h; live never. A pull closed without merging puts the issue back at issue; a re-opened pull counts from the re-open; with several open pulls the furthest along speaks. An issue is linked to a pull by Closes #N in the pull's body, as the merge itself reads it.

The forge's pipeline

src/flow/pipeline.ts is the same road seen from the machine, across every repository: ready → building → check queue → checking → review → approved → landed → live, each with how much waits in it, how much is being worked, how long its oldest waiting item has waited, and what limits it (crew runs at once, checks at once, the autonomous repositories' slots). The stage whose oldest waiting item has waited longest is the bottleneck. A forge admin reads it at /flow (web/pages/flow.ts), one row per stage under one sentence naming the bottleneck; the knobs stay on Settings → Capacity. The same sentence (verdict) is the terminal's admin-only Flow command and the MCP flow tool, which also returns the stages; anyone but a forge admin is refused.

readStepStats (same module, #7784) measures the road's steps over the last 30 days: median time (finished − started) and red rate (failed ÷ ok + failed) for the pull check, review, proof, merge-queue gate (time only: check_gate keeps a week and no verdict), main's check, release build and verify. The boot check runs inside the release build and has no run of its own. Review's rate counts review runs that errored, not changes asked, and says "errored". /pipeline shows them under each step's details, from public repositories alone, held in memory for the minute so the open page costs one read a minute. The same numbers, private repositories included for the owner, are the terminal's Flow dialog ("Steps, 30 days") and the steps array of the MCP flow tool and /api/v1/telemetry/flow (public repositories alone for an agent).

Polling /api/v1/telemetry/flow

The answer is a copy computed in the background and at most FLOW_TTL_MS (5 s) old, so polling faster than every 5 s only re-reads the same copy. Poll no faster than every 5 s, and send if-none-match with the last etag: a repeat on the same copy is 304 with no body. The response carries cache-control: private, max-age=<seconds until the copy is 5 s old> (wait that long), vary: authorization, cookie (the server appends Accept-Encoding on the wire), and an etag made from the reader kind and the copy's computed-at time (the body is never hashed). A 304 is still counted and still comes after the auth and scope checks. To find a reader that is too fast, look at forge_telemetry_reads_total{route="flow",reader=...} on /metrics: its rate (rate(...[5m])) above 0.2 per second is faster than 5 s. The MCP flow tool is unchanged.

Rebases

Approved work lands before new work is built, in the check lane too (#6140). A check on a pull whose last builder's run brought it up to date (a conflict run; a review after it does not count) goes before any other queued check (checks/finishing_first.ts). So the room for more rebases (crew/conflict_room.ts) is the check slots minus the rebases' checks and the bring-up-to-date runs in flight; a new build's check does not stand in front of a rebase and takes no room. The finishing pass (crew/finishing.ts) gives the update to the builder who can push the pull's branch — the fork's owner, else its author — and when that builder already has a run in flight the update queues behind it: lent to another builder, it could never push (#7006).

New work is the other way round: the decider's choice of builder is a ranking, and the most preferred builder with nothing in flight takes the issue (rankedBuilder in crew/route.ts), so the slots run more than one builder. The tick line's idle field counts the builders with nothing in flight beside active and slots.

The tick line's lane field, the Rebases: line on /flow and in the terminal's Flow, and rebases in the MCP flow tool all read conflicted N, rebasing M, room R: the conflicted pulls (with the approved ones still waiting for room, which have no run yet), the bring-up-to-date runs and their checks in flight, and the runs the lane has room to start now.

Red batches

src/flow/red_batches.ts readRedBatches(db, now, publicOnly) says, of the merge-queue batches judged in the last 6 hours, how many went red: { finished, red, rate }, rate null when none finished. A batch is one candidate the queue judged (checks/queue.ts calls onBatch beside its in-memory hourly count): a red batch's bisection prefixes and its head gated alone are its search, not batches; re-checks, cut-off gates and pull checks are not counted. Each verdict is a row of queue_batch, kept a week. The publicOnly rule is readVitals's. Nothing shows it yet (#5930).

What a red batch was (#7639)

src/flow/culprits.ts keeps one queue_verdict row per red the queue names (onVerdict, a week): real — the search found the one pull, handed back to its builder with the failing tests named, the rest of the batch landing — or load — infrastructure twice (install, setup, timeout) or a flake, no pull blamed or handed back. flowFor carries redBatches (counts over 24 h, the newest five, a sentence) in the MCP flow report; boards query the queueVerdicts source. Not done: a pause switch and the "fixed / still there" effect probe, which belong to the maintenance board (#7561) once it exists. The terminal Flow dialog lists them too; the how-to is docs/features/red-batches.md.

Throughput

src/flow/throughput.ts counts what each pipeline stage let out over the last 24 hours, hour by hour, from the same records (no table of its own): issues started (the first builder start per issue), pulls opened, checks started, checks finished (passed or failed; cancelled is not finished), reviews returned (review runs that finished ok), landed (merged into a default branch), released (release rows whose preflight passed), live (production deploys serving). It also gives the median ask→live over the merges that went live in the last 24 hours: from the oldest issue the pull closes (the pull itself when it closes none) to the first production deploy created after the merge serving.

On /flow each stage's row shows its count for the last hour, a 24-bar sparkline (oldest on the left) and the 24-hour count; the headline adds "landed N in the last hour · M in 24 h · median ask→live X h (24 h)". The sparkline is a picture only (aria-hidden, no links, no tab stops): the two counts beside it are the way in, two tab stops per row. Each count links to /flow?out=<what>[&hour=0], which lists the items it counted (any hour from 0 to 23 may be asked for by hand); an unknown out or hour lists nothing.

The MCP flow tool returns the same numbers under throughput: says (the headline sentence), medianAskToLiveMs, and per stage key, out, label, lastHour, day and hours (24 counts, 0 the last hour). The terminal's Flow command, a forge admin's like the page, opens a dialog with the bottleneck sentence, the headline and one line per stage of its last-hour and 24-hour counts. A sealed issue is counted, its title is not shown.

Under the pipeline, /flow shows each autonomous repository's ready list as one bar (#2244): what a builder could start beside the count per filter that holds the rest — crew/held.ts's heldBy, the same counts the autonomy tick logs as held=, read through flow/held.ts, which keeps the rows 5 s. The terminal's Flow command prints the same rows, one line per repository (alice/engine startable=0 stalled=4 run_cap=1). A granted agent sees public repositories only, on both.

One of those filters is the hot-file WIP limit (#5934, crew/hot_files.ts): a ready issue that names a file 5 or more open pulls already touch is held as hot_file until that pile drains under 5, so a sixth pull never joins a file every landing would make the rest rebase. An issue's expected files are the repository paths its title and body name (src/http/mcp.ts, ` README.md ); an open pull's files are read from git once per head before the picker sorts. The tick line names the hot files (hot=src/http/mcp.ts=61), and each repository's writers see one post on the feed — on the web and through the MCP feed tool — saying which build waits on which file, gone when the hold lifts. A pull whose diff touches more than 60 files counts toward no file's heat and is named on the feed (too wide to count: #4840 (1,081 files)`), even when no build is held.

Flow reads, in one page

bun scripts/flow-report.ts [--db <path>] [--public] [--json] (database read-only, default forge.db under FORGE_DATA; --json for raw values) prints one line per read of src/flow/report.ts: build_yield (agent runs finished in 24 h: how many pushed, landed, closed), review_latency (median hours from opening to first verdict), outsiders (open pulls by non-writers and non-crew, oldest in hours), checks_pile (open pulls red or waiting for a check slot), gate_minutes (check-slot minutes in 1 h and 6 h), oldest_approved (the longest-waiting approved pull), idle_pulls (crew pulls untouched for 72 h), lead_time (opening to landing, 24 h) and openers (who opened the last hour's pulls). The script reads everything; --public cuts it to public repositories.

Red pulls that sit (#8245)

src/crew/stale_reds.ts sweepStaleReds(app, repo, now, room) runs each autonomy tick and reads only the database, so a restart or roll loses nothing. An open crew pull whose latest check on its head failed, with no run in 30 minutes and no person holding or assigned to it, is re-checked (reason sweep); still red, its builder is queued with the failing test named, within the free slots and 3 a tick. Past its tries it is parked and its issue is ready again. Red for over 24 h and conflicting with main, or with its issue closed, it is closed with one line. The flow report's stale_reds line (src/flow/stale_reds.ts) counts the ones not yet handled, and the keeper names stale_reds as a cause from 3.

How a person sees stale reds: bun scripts/flow-report.ts prints the stale_reds: line (count and oldest hours), and the keeper names stale_reds as the cause when they are what holds the flow; the terminal Flow dialog draws the keeper's line (keeperLine), so it shows there when the keeper picks that cause. It has no line of its own on the dialog.

Estimates (#11955)

Estimates are recorded against an issue, asked for from the forge's own history and scored: see docs/features/estimates.md.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs