Clogs: prevent them (inflow governor, hot-file limit), say so at the top of home within 15 min, and a /flow page to clear one in two clicks #5930

Owner, 2026-10-25: "these kinds of clogs are what I want the forge to not run into, but if it does I need a fantastic UX to deal with it and be made aware."

The clog that prompted this (forge #5924):

• 199 open pulls: 116 approved, of which 60 were conflicted.
• Opened 51 against landed 15 per hour.
• 61 pulls collided on src/http/mcp.ts.
• It took the owner's eye to notice it. The home page never said so, and the only places it showed were the steward's probes and the autonomy tick line (approved="116 approved: conflict=60 …").

1. Don't clog (prevention, automatic)

• An inflow governor. When opened per hour stays above 1.5× landed per hour for 2 hours, or open pulls exceed 3× hourly landing, the picker lowers its own build slots, and it raises them back as the pile drains. The change and its reason show on the feed ("Builders 7 → 3: 51 opened vs 15 landed last hour").
• The hot-file WIP limit (#5924, step 3): a build is not started when its expected files overlap one that 5 or more open pulls already touch.
• Append-only registries become one file per entry, with a lint flagging any new file that grows by appends across more than 10 pulls in a week.
• Red batches bisect in parallel across idle check slots (all halves at once), not 8 → 4 → 2 → 2 in series.

2. Be made aware (detection)

A flow vitals set, measured every minute:

• open pulls
• opened and landed per hour
• the conflicted, queued, red and outsider counts
• the oldest approved wait
• gate minutes
• the red-batch rate
• stranded $: crew spend on pulls that are open and unlanded

A clog is declared on thresholds (for example, conflicted > 10, or landed < 50% of opened over 2 h, or the oldest approved wait > 24 h). Then:

• A banner on home, at the very top (not in the feed), with one sentence written from the data: "Clogged: 60 approved pulls conflict on src/http/mcp.ts (61 open pulls touch it). $X of crew work is waiting to land."
• A push notification to the owner, once per clog, with no repeats while it stands.
• The KPIs: time to detect under 15 min, time to clear tracked, stranded $ tracked.

3. Deal with it (the clog page, /flow)

• The pile as a funnel: building → checking → in review → approved → queued → landed. Conflicted, red and held hang off it as side branches, and each count opens its list.
• Hot files: the files the most open pulls touch, with a bar per file.
• One diagnosis and its fix, each a button with a preview of what it changes, every one a fleet op with Undo:

- "Lower builders to 3 until the pile drains" - "Hold new work on src/http/mcp.ts" - "Re-cut the 60 conflicted pulls onto main, oldest first" - "Close pulls stale more than 7 days and fold them back into their issues"

• Automatic first steps within rules: the governor acts on its own and the page says what it already did ("I lowered builders to 3 at 20:41"). A person decides anything that discards work.
• When a clog clears, a short note is posted automatically: cause, time to detect, time to clear, stranded $, and the detector or rule added so this class doesn't recur (the same escape rule as #5846).

Done when

• A seeded clog in a preview (100 pulls appending to one file) is prevented by the governor and the WIP limit.
• When those are forced off, the clog is detected within 15 minutes, with the banner and the notification.
• It's cleared from /flow with two clicks.
• A cold-read agent (#5735 method) given only the home page can say what's clogged and what to press in under 15 s.

Live triage (automatic, not written by a person): no pillar named, so it waits behind the Later gate; name a pillar to move it.

Owner, 2026-10-26: "this can't keep happening. How do we listen for these blocks? What is the alarm you need to set for the crew? I don't want to just keep stacking things on top and make it worse."

This issue is now THE flow alarm, the one place for it. Every block today had one shape: work sat still and nothing said so. The invariant is nothing approved sits still, with four alarms:

Already running in the steward's tick (a probe against the forge DB, every tick). First reading, 16:10Z: 55 approved pulls still for 30+ min; the oldest is #3885 at 5.5 days (approved, red check, never acted on).

Done when the forge owns it:

1. The four alarms are computed in the forge and shown as the clog banner on home and /flow (this issue's UX), with one notification to the owner when one fires.
2. Every alarm states the reason a pass skipped the item. That needs #6263's logging; the passes (finishing, requested, sweep, picker) must never drop work silently.
3. Escalation instead of silence: any pass that gives up on a pull hands it to a person visibly, as an item in "needs you" with the reason.
4. An approved pull that has been red 24 h or more gets one re-check, then goes back to its builder with the failing test, or is closed with a note.

Today's flow issues, in the order they matter (no new ones):

1. #6263: the finishing pass gave up silently after transient failures.
2. #5994: CI lockups.
3. #6217: the tools/list budget.
4. #6001: the pipeline levers.
5. #5924: the pile drain.

Steward, 16:15Z: what unclogging taught us. Fold these into the forge, here. Sorting the 55 stuck approved pulls showed these silent traps:

1. Handed to a person = invisible. When a pass gives up, it assigns the pull to the owner (e.g. #4413 → trevato). The crew then treats it as "a person holds it", and nothing tells the owner: no feed item, no notification. Fix: every hand-over shows in "needs you" with the reason and one button: "Give back to the crew" (re-assigns to the builder). Re-assigning #4413 to Scout started a run at once.
2. Holds outlive their reason. The steward's "red alone, held" holds stayed on 7 pulls after they turned green. Fix: a hold carries its reason and releases itself when the reason clears (check green on the same head, or main moved), or expires after 24 h with a note.
3. Infra failures count as the pull's failures (#6263). Two network blips froze conflicted pulls for hours.
4. Approved but red, for days. #3885 was approved but red for 5.5 days. Fix: after 24 h red, one re-check; if still red, back to the builder with the failing test; if the builder can't, close it with a note.
5. Verdicts and comments don't reach builders on approved pulls. Comments go to the reviewer; a changes-requested verdict on a held pull goes nowhere. Fix: the pull page shows who acts next and why, for every open pull.

Unclog run, 16:10Z: released 7 stale holds (all green now); queued 8 re-checks (red but clean); reassigned #4413 to its builder (run started). The 38 conflicted are next, once #4413 proves the path.

Owner, 2026-10-26: "much work has happened async because of these clogs. Having the work in private trees can lead to that, but it is the design that I find best for signal to noise ratio."

Keep private trees; measure their drift. Add a fifth signal to the flow alarm:

The alarm names the most-behind ones. Rebase them early, while it's cheap, before they become the next conflict pile. On a clogged day (the clog banner up), builders should rebase before building more in their own trees.

Steward, 16:45Z: the freeze leaked. The crew's direction said "FLOW ONLY, start no new feature work", yet 31 new feature pulls opened in an hour, mostly from issues filed today and then assigned. Assignment dispatches straight to a builder, so a direction can't stop it. Open pulls went from about 100 to 142 while the drain ran, and the new pulls took check slots from the rebased ones (5 landed that hour).

Needed in the forge: a real "flow only" switch per repo (a setting, shown on home and the repo header). While it's on:

• Only issues labelled flow (or the explicit list) may start builds.
• Rebase, re-check and review runs always go.
• Assignment to other issues queues the issue until the switch is off, instead of dispatching it.

When the clog banner fires, the forge should offer to turn the switch on, and turn it off itself when the four alarms have been clear for 24 h.

Steward, 18:13Z: one more silent hold. #5666 sat 36 h green, approved on its head and merging cleanly, but never joined the queue. The queue's in-memory "told red on this head" mark keeps a pull out until its head changes, even after main has moved hundreds of landings and the pull's own check is green. Fix: the mark expires when main moves (a new base means a new chance), or after one fresh green check on the same head. Show it as "red alone at <time>, waiting for a new head" on the pull, so it isn't invisible. Steward unblock: re-assigned #5666 to its builder for a fresh head.