Feature flags, part 3: each request's variant is counted, and Settings → Flags shows the A/B read-out for 7 and 30 days with one button to make the winner the default #2159

This pull shows each flag's reads per variant for the last 7 and 30 days in Settings → Flags. It adds a button that makes the winner the default.

The check that parked #2142 failed in test/report-discovery.test.ts ("a stranger's MCP body is read to a hard limit…"). That test doesn't touch flags, and it passes on this branch: I ran it three times in a row after merging the latest main. I could not reproduce the failure, so I think it was a flake in the early 413 response to an oversized or chunked body. The forge's check was not run here, so I can't rule out a real fault that only shows there. I changed nothing in the report or MCP path.

Since the last push I merged main and pushed again to re-run the check. The flag tests and tsc pass.

What changed

• Counting: each flag() read is counted in memory by UTC day and variant (on or off). The counts go into the new flag_use table in one batch every 10 seconds and again at shutdown, so a request runs no extra query. A failed write keeps the counts for the next try. The issue pointed at src/core/usage.ts, but that is the agent-run ledger and usage_count has no writer, so I added flag_use instead.
• Read-out: each flag row shows "Uses, 7 days" and "30 days" as on N · off M.
• Make the winner the default:

- The button appears when the 30-day counts differ. - It opens an issue on the forge's repository asking the crew to remove the losing path and the flag. The issue is opened first, so if that fails the flag is left as it was. - Then it sets the flag to the winner for everyone, which clears the user, role and percentage rules.

• Tests: in test/flags-settings.test.ts, covering the fixture counts for both windows, no query on a read, a failed flush keeping its counts, and the winner flow opening the issue and flipping the flag. The README has a paragraph on all of this.

Left out

• The counts are reads, not distinct people.
• The leader is picked by raw count, with no significance test.
• There is no terminal screen for the read-out.

Try it: as an admin, open /settings/flags. No flag is declared yet, so the page shows nothing until the first one is added.

Closes #1829

The terminal Flags screen now has the 7/30-day read-out and a key that makes the winner the default, so both doors can do it. The flag tests, the terminal-screen tests and tsc pass. I haven't seen the page or the screen running outside the tests.

Terminal

• Read-out: the screen's header line shows Uses, 7 days: on N · off M · 30 days: on N · off M for the flag under the cursor. I put it there because it was cut off when added to the row text.
• Winner key: w calls makeWinnerDefault and shows the new issue number, or the refusal. It has the same admin, non-agent gate as the screen's set.
• Row hint: a flag with a winner on offer shows w: make on/off the default in its row.
• Test: the new case in test/tui-flags.test.ts fails without the key. It checks the read-out, that w sets {forge} and opens the issue, and that a second w opens nothing. The non-admin and agent test now presses w and checks no issue is opened.

The action (src/actions/flag_winner.ts) now checks the admin gate itself, so neither door can skip it.

Your smaller points

1. The button and key now show only when the flag's explicit forge value differs from the leader. A flag that merely defaults to the leader still gets the offer, because the removal issue is still useful there.
2. I added a minimum: 50 reads in 30 days, no tie, otherwise no offer. 50 is my guess, so change MIN_WINNER_READS in src/core/flags.ts if you want a different bar. A test covers the too-few, tie and already-set cases.
3. The README paragraph now covers both doors and the rule for when the offer shows.

One thing I left alone: the server accepts whichever variant the form posts, not only the offered one. Both doors are admin-gated, so I judged it harmless.

makeWinnerDefault now decides the winner itself, so neither door can set a flag the read-out doesn't back. I couldn't verify the 360px layout.

• Winner gate:

- The action computes winnerOffer(uses(30), value(name)) and refuses with "That variant is not the winner yet." unless the requested variant equals the offer. - That covers too few reads, a tie, and a variant that is already the value. The page, the terminal and any other caller go through it. - The refusal happens before anything is opened or changed.

• Test:

- In test/flags-settings.test.ts, posting the unoffered winner=on now redirects, leaves the flag as it was and opens no issue. - Posting the offered winner=off sets {forge: false} and opens the issue with title "keep the off path". - The existing unknown-flag case still opens no issue.

• Header comment: rewrapped in src/tui/screens/flags.ts.
• Phone layout:

- Before this change the flag form could overflow at 360px, even without the new button. - I added a flag-form class so the controls wrap, and on screens up to 640px the controls drop under the flag's text and the inputs shrink. - I checked this against the CSS only. The headless-browser test (test/web-phone.test.ts) can't start Chromium in this sandbox, so it fails here and says nothing about the page. The forge's check will exercise it, and nobody has looked at the flags page at 360px.

The flag and terminal-flag tests and tsc pass.