Public: anyone can read this; the crew can change it.
The maintenance board names the one stalled step in the flow and the single action that unblocks it #14527
Check · Review · Land · Live done — Landed and live in production.
/maintenance now shows at most one "Stalled" card at the top, naming the oldest stalled step, its age and one button. The new test passes, tsc and design-lint are clean, and gate --fix rewrapped comments in two files, which are committed.
shipped production is serving it deploy 8e4256e
17 earlier comments · 4 events
/maintenance now shows at most one "Stalled" card at the top, naming the oldest stalled step, its age and one button. The new test passes, tsc and design-lint are clean, and gate --fix rewrapped comments in two files, which are committed. I ran only the tests around this change (test/maintenance-stalled.test.ts, test/maintain-stale-web.test.ts, test/maintenance-page.test.ts, test/maintenance-filed.test.ts, test/a11y-landmarks.test.ts), not the full suite. The push went through on the second try, after a pre-push hook asked for a commit saying how to try the change.
What I took "the stalled step" to mean. The issue doesn't define it, so I chose the one the board can already measure: an open pull with no push, comment or review for 14 days, which waits on a person. If you meant another step (a tell nobody picked up, or the drain during maintenance), this needs a different finder and button.
- The card. It reads "owner/repo#N waits for review", with the age in days and "N other(s) wait too" when more than one pull stalls. Nothing renders when no pull is stale. The logic is
stalledStepinsrc/maintenance/stalled.ts, and the card is insrc/web/pages/maintenance.ts. - The button. "Ask if still wanted" is a POST to the existing
/maintenance/stale/:id/nudge. That route already does the same-origin check, the admin check, a comment on the pull, and a receipt in the flash and the maintenance runs. An agent-kind admin sees the card without the button, as with the existing stale-pulls fold. - Test.
test/maintenance-stalled.test.tschecks no card with no stalled pull, then with two stale pulls checks one card, its age, the count, and a single POST form. It also checks that a cross-origin press is refused and that a same-origin press redirects (303) and writes a maintenance-run receipt.
Left out:
- Steps other than stale pulls.
- Any new action: Close stays in the existing stale-pulls fold.
- A card on
/system.
Try it: as an admin with a pull untouched for 14 days, open /maintenance and press "Ask if still wanted".
🤖 Generated with Claude Code
<!-- look-pages 74062bb89bd2 --> Look pages for 74062bb, from the gate:
look pages (inferred): this pull changes src/web/pages/maintenance.ts; the forge pictures /system (src/web/pages/maintenance.ts), /maintenance (src/web/pages/maintenance.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
/maintenance now names the one stalled step, its age and the button that unblocks it. That change is already on the pull. This push only adds commit-message lines for the two gate rules that were failing. No code changed.
- Pipeline first: an empty commit carries
Direction: … (#14504). The pull adds a feature and touches no pipeline files, so the gate wants a stated reason. I did not add a pipeline change. - Both doors: the same commit carries
No door: …. The stalled step shows on the existing/maintenancepage, so I added no new terminal screen ordocs/featureshow-to. If review wants a how-to, that is a separate addition. - Look pages: the commit also carries
Looks: /maintenance, so the gate pictures that page instead of inferring it.
I ran bun scripts/gate.ts locally and it passed. I did not re-run tsc or the tests, since nothing in the code changed. The forge's check on this push is the real verdict.
To try it: as an admin with a pull untouched for 14 days, open /maintenance and press Ask if still wanted.
No code change is needed for this feedback. The look-pages comment was written against the earlier commit 74062bb, where the gate inferred /system and /maintenance from src/web/pages/maintenance.ts. My latest commit, ec11e65, carries Looks: /maintenance. The gate now reports "look pages (named)", so the forge pictures only /maintenance.
I left /system out on purpose. This pull changes only the maintenance board. /system appeared in the inferred list only because it shares src/web/pages/maintenance.ts, and its output doesn't change. If you want /system pictured too, say so and I'll add Looks: /system.
Nothing new is pushed.
What the pull does: /maintenance names the one stalled step in the flow, its age, and the single button that unblocks it. The logic is in src/maintenance/stalled.ts and is rendered by src/web/pages/maintenance.ts.
What I left out:
- A new terminal screen and a
docs/featureshow-to, because the stalled step shows on the existing/maintenancepage. The commit'sNo door:line says this. - A pipeline change. The commit's
Direction:line gives the reason (#14504).
To try it: as an admin with a pull untouched for 14 days, open /maintenance and press Ask if still wanted.
<!-- look-pages ec11e65cfcde --> Look pages for ec11e65, from the gate:
look pages (named): this pull changes src/web/pages/maintenance.ts; a commit names /maintenance
This comment is the gate's automatic note for ec11e65. It confirms the Looks: /maintenance line was read ("look pages (named)"), so there is nothing to change and I pushed nothing.
What changed: /maintenance names the one stalled step in the flow, its age, and the single button that unblocks it. The logic is in src/maintenance/stalled.ts and is rendered by src/web/pages/maintenance.ts.
What I left out:
- A new terminal screen and a
docs/featureshow-to, because the stalled step shows on the existing/maintenancepage (theNo door:line inec11e65says this). - A pipeline change; the commit's
Direction:line gives the reason (#14504). - A picture of
/system, which shares the page module but whose output doesn't change.
To try it: as an admin with a pull untouched for 14 days, open /maintenance and press Ask if still wanted.
I merged main into the branch and pushed; the merge conflict is resolved. The maintenance tests pass (64 pass, 0 fail across 13 files) and tsc --noEmit is clean. I did not run bun scripts/design-lint.ts after the merge: it was in the same command that timed out, and I didn't re-run it. The forge's check runs on the push.
/maintenance now has the ?level= filter and strip from main and the stalled-step card from this pull. The conflict was in src/web/pages/maintenance.ts: I kept main's level sections and moved the stalled-step card to sit right under the status line. The card is hidden on the calm "For information" view, the same as the status line.
What to look at:
- Open
/maintenanceas an admin with a pull untouched for 14 days. The card should show with its Ask button, and disappear on?level=fyi. bun scripts/gate.ts --fixflagged the helper functions intest/maintenance-stalled.test.tsas near-copies of ones in other test files. Those were already on the branch before the merge, and I left them alone.scripts/fast.tssaid the diff reaches 2228 test files and would take over 3 hours, so I ran the maintenance test files by hand instead of the set it names.
<!-- look-pages 4fe4298b66ab --> Look pages for 4fe4298, from the gate:
look pages (named): this pull changes src/web/pages/maintenance.ts; a commit names /maintenance
The board change works as scoped: one card, oldest stale pull, one POST button that reuses the existing same-origin-checked nudge route, and a test for card and no-card. Two things block it.
First to fix: Both doors. A person can see the stalled step and press the button on the page, but the terminal has no way to do either. Add a screen in src/tui/ (entered where AGENTS.md says) that shows the same stalled step and presses the same nudge, gated like the page (admin only, no agent-kind button), and add docs/features/maintenance-stalled.md with the how-to (not README). The 'No door:' commit line does not satisfy this; the existing /maintenance TUI screen, if there is one, must show the card too, with a test.
Second: the card copy and markup (see line comments): '1 days' is wrong grammar, 'waits for review' is stated as fact when the pull is only untouched, and the card is hand-rolled markup rather than a named component/row from docs/DESIGN.md. Also the test helpers were flagged by the gate as near-copies of other tests; reuse the shared helper instead of a fourth copy.
Judged against the issue boxes: 1 and 2 are met on the web, 3 is met.
/maintenance now names the stalled step as a plain row, and the terminal's Maintenance screen shows the same step and presses the same nudge. Tests pass (86 across the maintenance, stale-pull and door tests), tsc is clean and the design lint is clean. I did not run the whole suite; the forge's check does that.
Page (src/web/pages/maintenance.ts)
- The hand-rolled section is now a "Stalled" row in the board's own status-row pattern. The button is the existing outline button, still shown only to people.
- The copy comes from one place,
src/maintenance/stalled.ts. It readsr#3 untouched for 1 day(singular handled), then; 1 other pull is quiet too. It no longer says "waits for review".
Terminal (src/tui/screens/maintenance.ts)
- The existing Maintenance screen shows
Stalled: <repo>#N untouched for N days (a asks if still wanted), andapresses the samenudge. - The line and the key appear only for an admin who is a person, and not on the "For information" view (
l). A pull whose finding was quieted for the day is left out, as on the page. test/tui-maintenance-stalled.test.tscovers three cases: no line when nothing stalls, the oldest pull shown andaposting the comment, and a non-admin seeing nothing and the key doing nothing.
How-to: docs/features/maintenance-stalled.md.
Test helpers
test/helpers/stale-pull.tsandtest/helpers/tui-maintenance.tsreplace the copied helpers in the stalled, stale-web and tui-quiet tests. The seeding helpers also come fromtest/helpers/admin.ts. The gate's near-copy notes are gone.test/maintenance-level.test.tsexpected the terminal's Needs-you view to be empty. Its fixture holds a stale pull, which is exactly what now shows there, so I changed the expectation; the old one was incidental.- One of my pushes went out while that test was red. The follow-up commit fixed it.
Look pages: the gate's note is informational. I named /maintenance in a Looks: line in the commit message.
Left out: the TUI shows only the single oldest stalled pull, as the page does. The full list is still on the "Pulls untouched for 14 days" screen.
[
{"go": "/maintenance as an admin with a pull untouched for 14+ days", "look": "a Stalled row under the status line: repo#N, 'untouched for N days', a count of others, one 'Ask if still wanted' button", "expect": "no 'waits for review' wording; one day reads '1 day'; no card when nothing is stale"},
{"go": "/maintenance?level=fyi", "look": "the Stalled row", "expect": "absent on the calm view"},
{"go": "ssh in as an admin, open Maintenance, press a", "look": "the first line 'Stalled: …' and the receipt after pressing", "expect": "a nudge comment lands on the pull; a non-admin sees no line"}
]<!-- look-pages 3e952d03cf42 --> Look pages for 3e952d0, from the gate:
look pages (named): this pull changes src/web/pages/maintenance.ts; a commit names /maintenance
The maintenance board now shows the one stalled step as a row (the pull, how long it was quiet, one button), and it also has a terminal door. I pushed a fix for the one failure this pull caused. test/counts.test.ts, test/tui-maintenance-stalled.test.ts, tsc, scripts/gate.ts --fix and design-lint all pass locally. I did not run the full suite; the forge does that on the push.
- Failing test: "an issue listing costs the same for 5 rows as for 50" was timing-dependent, not broken by the stalled-step code. Locally it failed 2 runs in 8 (once with 17 statements for the first request against 8 for the second), so I think a cold first request or background work was landing in its window. The test now makes one throwaway request before it counts. It passed 4 runs in a row after the change; I did not reproduce the original failure on main.
- Merge: I merged
origin/maininto the branch.src/web/pages/maintenance.tsconflicted, and I kept both sides: the stalled-step card and main'smaintenanceJsonandmaintenancePagehandlers. - Other five failures: the sweep of src, the pages budget, the
llms.txtbudget, the first-page SQL statement budget and the fetch timeouts. The check log says they are red on main at c0abde6 too, so I left them alone. - Left open:
scripts/gate.tsflaggedopenMaintenanceintest/helpers/tui-maintenance.tsas 0.64 similar toterminalintest/flow-waiting.test.ts, and I did not merge the two.
[{"go":"/maintenance","look":"a pull that has been quiet too long shows a Stalled row above the board with one outline button","expect":"the row names the pull and how long it was quiet; pressing the button posts once; with no stalled pull there is no row"}]
🤖 Generated with Claude Code
<!-- look-pages cd39404e392c --> Look pages for cd39404, from the gate:
look pages (named): this pull changes src/web/pages/maintenance.ts; a commit names /maintenance
Nothing in the pull's own code was red this time, so I changed no code. I merged the latest origin/main into the branch and pushed; the check will run again on that.
The only failure the check blamed on this pull was "POST /api/v1/apps names its phases and answers under 1 s", from test/new-app-post-timing.test.ts. It missed its 1 s budget by 6 ms (1006 ms) while the full suite ran across shards. Three local runs of it passed, and this pull doesn't touch the apps API. I didn't loosen the test. If it fails again on a quiet run, the cause is somewhere else, not this pull.
The other six failures (the page budgets, the llms.txt budget, the outbound-fetch sweep, the <time> check and the fetch timeouts) are red on main at 42e919a too, so the check doesn't count them against this pull.
After the merge, tsc is clean. test/new-app-post-timing.test.ts, test/tui-maintenance-stalled.test.ts and test/counts.test.ts pass together (12 tests). scripts/gate.ts still flags openMaintenance in test/helpers/tui-maintenance.ts as similar to terminal in test/flow-waiting.test.ts; I haven't merged them.
I merged main into the branch and pushed. The only conflict was test/counts.test.ts.
Both sides had fixed the same timing flake in "an issue listing costs the same for 5 rows as for 50". I kept main's fewestStatements version and dropped the warm-up request I had added earlier, so the pull no longer touches that test.
tsc is clean, and test/counts.test.ts and test/tui-maintenance-stalled.test.ts pass together (10 tests). I did not run the rest of the suite; the forge's check does that on the push.
<!-- look-pages 3f2462deb034 --> Look pages for 3f2462d, from the gate:
look pages (named): this pull changes src/web/pages/maintenance.ts; a commit names /maintenance
Earlier asks are met. The stalled step is now a plain Stalled row in the board status-row pattern. The wording says only what is known ("untouched for 1 day"), with no review claim. The terminal has a door: the first line on the Maintenance screen, key a through the same nudge, admin people only and left out of the calm view. The how-to is docs/features/maintenance-stalled.md, README is untouched, and the test helpers are shared instead of copied. Tests cover no card, one card with its POST form, a refused cross-origin press, a receipt, and the TUI for admin versus other users.
Non-blocking: remove the doubled blank line after stalledCard in src/web/pages/maintenance.ts. Non-blocking: openMaintenance in test/helpers/tui-maintenance.ts is similar to the terminal helper in test/flow-waiting.test.ts; fold them together later.
The two next things I would do: show the card on /system too, and add a Close action alongside Ask.
I removed the doubled blank line after stalledCard in src/web/pages/maintenance.ts and pushed. tsc is clean and test/tui-maintenance-stalled.test.ts passes (3 tests).
- Look pages: the gate's note ("a commit names /maintenance") needs no change. The new commit's subject names
/maintenance, and the page to look at is/maintenance. - Not done: I did not fold
openMaintenanceintest/helpers/tui-maintenance.tsinto theterminalhelper intest/flow-waiting.test.ts. @juniper marked that non-blocking and for later. The gate still flags the pair as similar. - Not done: I did not show the card on
/systemor add a Close action. These were suggested as next steps, not as part of this pull.
<!-- look-pages 760a3f6c877f --> Look pages for 760a3f6, from the gate:
look pages (named): this pull changes src/web/pages/maintenance.ts; a commit names /maintenance
Since 3f2462d the only change is a removed doubled blank line after stalledCard; my earlier asks stand met (copy from one place, the terminal door and its how-to in docs/features, the shared nudge route with its same-origin check and receipt). Nothing new to raise. Two things I would do next: (1) Non-blocking: fold openMaintenance in test/helpers/tui-maintenance.ts into the terminal helper in test/flow-waiting.test.ts, which the gate still flags as similar. (2) Non-blocking: show the same row on /system, and offer Close beside Ask if still wanted.
Nothing needs changing, so I made no commit or push this time. @juniper's approval has no blocking items, and the look-pages comment from the gate is the same note as before. The page to look at is /maintenance, and a commit on the branch already names it.
The desk hold says production is rolling and changes to it should wait until it settles. This pull doesn't touch production. It's a branch with a preview, and a person merges it, so the hold only matters at merge time. It's worth waiting until the release settles before merging.
I left @juniper's two non-blocking follow-ups for later pulls:
- Fold the helpers:
openMaintenanceintest/helpers/tui-maintenance.tsinto theterminalhelper intest/flow-waiting.test.ts, which the gate still flags as similar. - Extend the row: show the same Stalled row on
/system, and offer Close beside Ask.
/maintenancenow shows at most one "Stalled" card at the top, naming the oldest stalled step, its age and one button. The new test passes,tscanddesign-lintare clean, andgate --fixrewrapped comments in two files, which are committed. I ran only the tests around this change (test/maintenance-stalled.test.ts,test/maintain-stale-web.test.ts,test/maintenance-page.test.ts,test/maintenance-filed.test.ts,test/a11y-landmarks.test.ts), not the full suite. The push went through on the second try, after a pre-push hook asked for a commit saying how to try the change.What I took "the stalled step" to mean. The issue doesn't define it, so I chose the one the board can already measure: an open pull with no push, comment or review for 14 days, which waits on a person. If you meant another step (a tell nobody picked up, or the drain during maintenance), this needs a different finder and button.
stalledStepinsrc/maintenance/stalled.ts, and the card is insrc/web/pages/maintenance.ts./maintenance/stale/:id/nudge. That route already does the same-origin check, the admin check, a comment on the pull, and a receipt in the flash and the maintenance runs. An agent-kind admin sees the card without the button, as with the existing stale-pulls fold.test/maintenance-stalled.test.tschecks no card with no stalled pull, then with two stale pulls checks one card, its age, the count, and a single POST form. It also checks that a cross-origin press is refused and that a same-origin press redirects (303) and writes a maintenance-run receipt.Left out:
/system.Try it: as an admin with a pull untouched for 14 days, open
/maintenanceand press "Ask if still wanted".🤖 Generated with Claude Code
Closes #14504