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

One page that says where the bottleneck is right now: line, CPU, checks, model, disk, with the levers beside each #13723

Merged opened this in answer to

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

Merged

A first slice of /system/bottleneck is pushed, but the gate refuses it. I can't satisfy both of its rules for this pull. The page does not do most of what the issue asks.

Notes

shipped production is serving it deploy 4adf612

opened this

A first slice of /system/bottleneck is pushed, but the gate refuses it. I can't satisfy both of its rules for this pull. The page does not do most of what the issue asks. It is not tested against a full uplink, so "numbers match the host's within a tenth" is unverified.

Gate conflict: "both doors" requires a docs/features/<name>.md for a new page. "Small and single-purpose" allows at most 2 new feature files, and this pull adds 3 (doc, terminal screen, page). The pull needs either a Direction: justification that passes the size rule, or a split. I also folded the doc into docs/features/system.md as a test. That fails "both doors", so I restored the separate doc.

I ran tsc, bun test test/bottleneck.test.ts test/mcp-size.test.ts test/a11y-landmarks.test.ts and bun scripts/design-lint.ts before pushing. I also ran test/guide.test.ts and test/feature-orphans.test.ts during the doc fold, but not after restoring the separate doc. All of those were green. I did not run the forge's full check, which now runs on the push.

What changed

  • Page: /system/bottleneck is for the owner only. It opens with one sentence naming the row at 90% or more of its ceiling, for example "The uplink is full: 3.5 of 3.5 Mbit/s." If no row is that high it says "Nothing is at its limit."
  • Rows: line, CPU (split by pages, checks, crew and apps), checks (slots held and waiting), crew, memory and disk. Each shows its reading, its ceiling, a small line of recent readings, and a link to the control that moves it (/settings/capacity or /settings/backups).
  • Other doors: the same lines are in the terminal ("Where the bottleneck is", admin) and in the MCP system tool as kind: bottleneck, admin only. The reference is docs/features/bottleneck.md.
  • Line ceiling: it comes from a new FORGE_LINE_MBIT environment variable (megabits a second out). Without it the line row says no ceiling is set and never takes the sentence.
  • Code: the logic is src/system/bottleneck.ts, a pure judge plus a reader.

Left out

  • Round trips to outside hosts, the public-address versus loopback comparison, bytes split by sender, and the host's shaper. The page lists these under "Not visible from here" instead of guessing.
  • Marking when a lever moved, and the ask raised after ten minutes at a ceiling.
  • Work waiting by cause, the model row (upload size, week used) and a hosted forge's own share.
  • An admin-set ceiling in settings. I avoided a new capacity key because it touches the contract and its tests.
  • Recent readings are only noted while the page or MCP tool is read, at most one per 30 s, so a page nobody visits builds no history.

Try it: open /system/bottleneck on the preview as the owner. Set FORGE_LINE_MBIT to a low number to see the uplink sentence once the line carries traffic.

🤖 Generated with Claude Code

Closes #13712

Show 7 earlier items

7 earlier comments · 1 event
commented

I made no change and pushed nothing, because the feedback isn't a failure.

The look pages (named) line is the gate's informational note, not a failing check. Its source is src/kernel/look_rule.ts, and the (named) kind is the one it prints when a pull changes src/web/ and a commit names a pictured page. Here the pull changes src/web/pages/bottleneck.ts and a commit names /system.

/system is listed in app.looks in forge.json, so the forge pictures that page on the preview. The note's own text says nothing is required of the author. A Looks: or No look: line is only needed when the gate can't match the change to a page.

I didn't run the page checks or tsc, since nothing changed.

Changes requested — before the latest push

Changes needed, in one round:

  1. Both doors. The page and the MCP tool exist but the terminal has no screen (src/tui/, entry where AGENTS.md says). The checklist makes that a miss. If the 2-new-feature-file rule blocks it, put the how-to for the terminal in the same bottleneck.md (it is one feature) instead of dropping the door, or state the Direction justification.
  2. Doc is false. docs/features/bottleneck.md and the issue promise a last-hour line per row, but the history was removed. Either restore it (state kept under FORGE_APP_DATA, not a module Map) or delete the claim. Also drop the 'Left for later' list from the doc; it is a TODO list, not a how-to.
  3. Design (principles 1, 7, 8). Rows are hand-rolled <li> with <strong>, a parenthesised percent and a 'Lever:' line. A fact with a reading, a ceiling and a lever is a dl row (term, value, muted detail, the lever as the <a>). The page head sub and the bn-says sentence say the same thing twice; keep the sentence, drop the sub (1). 'Lever', 'uplink' and 'Not visible from here' are not plain words (WRITING.md) (8). data-limiting is set but nothing styles or reads it: mark the limiting row visibly with the existing muted/accent rules or remove it.
  4. Tests. The page test checks only the owner and an anonymous request; add a signed-in non-admin that gets 404, and an MCP test that a non-admin gets forbidden and an admin gets rows. judge has no test for the memory, disk or crew sentences or for a missing reading (not read yet); the new sentence branches need one each.
  5. Code. In sentence() the line row parses its own now string (r.now.split(" Mbit/s out")[0]): pass the number instead. The CPU now multiplies busyPct by limitCores ?? cores.length; confirm busyPct is relative to that same count, otherwise the row misstates cores. The line row's lever points to backup settings, which does not move the uplink; say there is none or link what does.
  6. Direction. This is a feature ahead of the pipeline list. It is defensible only for the checks row; keep the pull to what the issue asked and say in the description why it goes before #6534.
commented

This pull adds /system/bottleneck, a page where a forge admin sees in one sentence what limits the forge now, with a row each for connection, CPU, checks, crew, memory and disk. Each row shows its reading, its ceiling and the setting that moves it. The MCP system tool answers the same thing with kind: bottleneck. The new and affected tests, tsc and design-lint pass. I did not run the whole suite, and I did not run the page's look pages here.

What changed after review

  • Both doors: there is now a terminal screen, src/tui/screens/bottleneck.ts, offered to admins who are people and registered in entries.ts. /system now links to the page. docs/features/bottleneck.md covers all three doors in one file.
  • Doc: I deleted the "last hour" claim rather than building history. I also removed the "Left for later" list.
  • Design: rows are now status-row dl entries: term, reading with ceiling and percent, muted detail, and the setting as the link. The limiting row shows an "At its limit" badge. I dropped the page sub, since bn-says already says it. "Lever", "uplink" and "Not visible from here" are gone from the page: the headings are "Connection" and "Not measured here", and each link names its action, like "Set how many checks go at once".
  • Code:
    • sentence() now takes the number instead of parsing the now string.
    • The CPU row was wrong: busyPct is the mean over all the machine's cores, so I scale it by cores.length. The ceiling stays the forge's own limitCores, and the fraction is computed from those two. The old code used the limit for both, which understated the reading when a limit is set.
    • The connection row has no setting, since nothing in the forge moves it. Its lever is null and its detail says so.
  • Tests:
    • The sentence for memory, disk and crew, and a missing reading (not read yet).
    • The CPU scaling.
    • A signed-in non-admin on the page.
    • An MCP non-admin getting forbidden and an admin getting the six rows.
    • A terminal test for the screen and its palette entry.

Where I disagree or deviate

  • 404 vs 403: a signed-in non-admin gets 403 from an existing /system gate before the page runs, not the 404 the review expected. Either way they get nothing, and the test asserts 403 with no page content.
  • Direction (item 6): I did not drop any rows. I kept the page to what the issue asked for. The checks and crew slots are the part that matters most while the pipeline list (#6534) is still waiting, and the other rows come from the same live reading at no extra cost. If that ordering is still wrong, the checks and crew rows are the ones to keep.

To try it: sign in as an admin and open /system/bottleneck. Set FORGE_LINE_MBIT to give the connection a ceiling. In the terminal, open the palette and choose "Where the bottleneck is".

commented

<!-- look-pages 0e8843a1bfcc --> Look pages for 0e8843a, from the gate:

  • look pages (named): this pull changes src/web/pages/bottleneck.ts, src/web/pages/system.ts; a commit names /system
commented

The forge's gate refused the pull because it added 3 feature files and the limit is 2. I removed the terminal screen, so it now adds 2 (the /system/bottleneck page and its how-to). bun scripts/gate.ts passes after the change, tsc --noEmit is clean, and the 13 tests in test/bottleneck.test.ts pass. I pushed, so the forge's check is running again.

What the page does: /system/bottleneck gives an admin one sentence on what limits the forge now. Below it is one row each for the internet connection, CPU, checks, crew, memory and disk, with the reading, its ceiling and the setting that moves it. /system links to it. The system MCP tool answers kind: bottleneck with the same reading, and a non-admin gets forbidden.

What changed since the last push:

  • Deleted src/tui/screens/bottleneck.ts and test/tui-bottleneck.test.ts.
  • Reverted the src/tui/screens/entries.ts line that registered the screen.
  • Cut the terminal section from docs/features/bottleneck.md.

Left out: the terminal screen, which should go in its own pull. The page, the MCP tool and the shared reading (readBottleneck) are unchanged.

To try it: sign in as an admin and open /system/bottleneck on the preview at https://lab--13723--forge-trevato-apps.open-platform.sh.

commented

<!-- look-pages 591d98b5b848 --> Look pages for 591d98b, from the gate:

  • look pages (named): this pull changes src/web/pages/bottleneck.ts, src/web/pages/system.ts; a commit names /system
commented

The attention-budget test failed because I added a visible "Where the bottleneck is" link to /system. That put /system at 238 words and 78 blocks against budgets of 234 and 77.

I moved the link into the collapsed "? How to read this" help on /system, so it no longer counts in the first view. I left the budget file alone. The link is still reachable from the page.

test/attention.test.ts and test/bottleneck.test.ts pass here (15 tests). bun x tsc --noEmit and bun scripts/design-lint.ts are clean, and bun scripts/gate.ts --fix printed only a look-pages line naming /system, with no failures. I did not run the full suite; the forge's check does that on the push, which is now made.

I added no test for the link, so nothing fails if it is removed from the help.

commented

<!-- look-pages 337a3028830f --> Look pages for 337a302, from the gate:

  • look pages (named): this pull changes src/web/pages/bottleneck.ts, src/web/pages/system.ts; a commit names /system
commented

The feedback is the gate's look-pages note, and it reports that the check passed. It says this pull changes src/web/pages/bottleneck.ts and src/web/pages/system.ts, and that a commit names /system. It asks for no change, so I changed nothing and pushed nothing.

The note is about /system because the pull adds the "Where the bottleneck is" link there, inside the collapsed help. The bottleneck page itself is new, and I did not check whether the gate's look pass should name /system/bottleneck as well.

Approved

Approved. The page is owner-only and the MCP kind is admin-only, both with tests. The rows use the status-row dl, there is no new CSS, and it works with JS off. The CPU scaling is fixed, and the sentence logic is pure and covered. The how-to is in docs/features/bottleneck.md and README is untouched. The /system link sits in the collapsed help, which keeps it inside the attention budget.

Non-blocking: (1) The terminal door is missing. It was dropped to meet the 2-feature-file size rule, so open a follow-up pull for src/tui/screens/bottleneck.ts and its entry. (2) Nothing tests the /system help link; add one assertion. (3) The preview request I made as a bearer token got a 303, so I could not view the page there. I judged the page from the diff and its tests.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs