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

Merged opened this

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

Merged

/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.

Notes

shipped production is serving it deploy 8e4256e

opened this

/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 stalledStep in src/maintenance/stalled.ts, and the card is in src/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.ts checks 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

Closes #14504

17 earlier comments · 4 events
commented

/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 stalledStep in src/maintenance/stalled.ts, and the card is in src/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.ts checks 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

commented

<!-- 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
commented

/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 /maintenance page, so I added no new terminal screen or docs/features how-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.

commented

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/features how-to, because the stalled step shows on the existing /maintenance page. The commit's No 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.

commented

<!-- 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
commented

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/features how-to, because the stalled step shows on the existing /maintenance page (the No door: line in ec11e65 says 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.

the crew's run was interrupted: clone, resumes on the next pass — fetch failed: fatal: early EOF
commented

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 /maintenance as 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 --fix flagged the helper functions in test/maintenance-stalled.test.ts as near-copies of ones in other test files. Those were already on the branch before the merge, and I left them alone.
  • scripts/fast.ts said 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.
commented

<!-- 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
Changes requested — before the latest push

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.

commented

/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 reads r#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), and a presses the same nudge.
  • 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.ts covers three cases: no line when nothing stalls, the oldest pull shown and a posting 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.ts and test/helpers/tui-maintenance.ts replace the copied helpers in the stalled, stale-web and tui-quiet tests. The seeding helpers also come from test/helpers/admin.ts. The gate's near-copy notes are gone.
  • test/maintenance-level.test.ts expected 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"}
]
commented

<!-- 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
commented

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/main into the branch. src/web/pages/maintenance.ts conflicted, and I kept both sides: the stalled-step card and main's maintenanceJson and maintenancePage handlers.
  • Other five failures: the sweep of src, the pages budget, the llms.txt budget, 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.ts flagged openMaintenance in test/helpers/tui-maintenance.ts as 0.64 similar to terminal in test/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

commented

<!-- 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
commented

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.

commented

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.

commented

<!-- 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
Approved — before the latest push

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.

commented

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 openMaintenance in test/helpers/tui-maintenance.ts into the terminal helper in test/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 /system or add a Close action. These were suggested as next steps, not as part of this pull.
commented

<!-- 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
Approved

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.

commented

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: openMaintenance in test/helpers/tui-maintenance.ts into the terminal helper in test/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.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs