Efficiency watcher: network bytes and cache hit rates by cause, filed when a cost doubles #11257

Review changes are in and pushed. Gate and tsc came back clean. I ran 56 tests (the efficiency suites, maintain, board-windows, palette-roster) and all pass. scripts/fast.ts judged the diff too broad to name tests, so I picked those files myself.

What changed

• Cache hit rate cause. install-cache-hit-rate is new.

- Counter. meteredInstall now calls noteInstall(missed) after each contained install. An install counts as a miss when the registry sent more than NPM_MISS_BYTES (1 MiB). The tally lives in memory in src/efficiency/installs.ts and covers the last hour. A restart empties it, so the duty has no hit-rate reading for that hour. - Reading. The hourly reading is hits over installs, and there is none under 5 installs in the hour. - Rule. judge.ts has a new falling rule, with a direction on each cause. A hit rate at or under half its baseline for 2 hours running files. The floor is on the baseline: a cache that already hit under 50% of the time isn't "fallen from". Rising causes behave as before. - Wording. The issue title reads "far below its usual", and the number is shown as a percentage. - Docs and board. The efficiency board source docs and docs/features/maintain.md are updated. - Still unmeasured. Per-run bytes and peak memory have no counter, so they stay unmeasured and the docs say so.

• (1) Dedupe test. The second test now seeds egress-other-bytes history and asserts two issues, one per cause. It also asserts that a person closing the npm issue re-files only the npm one.
• (2) Missing FORGE_REPO. watch.ts adds the action filed nothing: FORGE_REPO is not set, …. It has variants for a malformed value, a repository that doesn't exist, and an owner that isn't a user. Tests cover the unset and nonexistent cases through the runner and watch.
• (3) Runner test. test/efficiency-runner.test.ts runs the registered duty through startMaintain. I removed app from the context in runner.ts and both runner-driven tests fail. I restored it.
• (4) Where an admin sees the series. Each run is a row under efficiency-watcher on the "Maintenance duty runs" screen, with each finding's probe. The series is the efficiency source on /boards (filter cause, value value). The runner test asserts the admin screen lists the duty and a non-admin sees nothing. I did not look at the preview or take screenshots.
• Tests added. test/efficiency-hit-rate.test.ts covers the counter, the falling rule and its floor, and a fall that files one issue.

Not done

• No absolute floor on the hit rate, such as "under 20% files at once". Only the falling-ratio rule exists.
• The tally is in memory rather than in SQLite. That keeps the install path free of writes, and an hour of data is cheap to lose.

This adds the efficiency-watcher maintenance duty (#7558). Every hour it records each cost by cause: npm registry bytes, other egress bytes, CPU-seconds, and the install cache hit rate. It compares each reading with the median of the same hour over the last 7 days. One issue is filed per cause when a cost doubles for 2 hours (for the hit rate, when it falls to half) or crosses a hard ceiling. The issue gets a comment each hour the problem lasts and is closed with a note after 24 hours back to normal.

This round, from review:

• Two readings in one hour (src/efficiency/store.ts): the worse reading now wins, chosen by the cause's direction. A falling cause (the hit rate) keeps the smaller and a rising cost keeps the larger. Before, the larger always won, so a second pass in the same hour (a restart or a manual tick) could hide a real fall in the hit rate. A new test in test/efficiency-hit-rate.test.ts covers this and fails when both directions keep the larger.
• "A single bad hour resets the wait" (test/efficiency-close-when-clear.test.ts): the test now checks that the issue is:

- still open 25 h after the first bad hours, when it would already have closed if the stray bad hour had done nothing; - still open 23 h 10 min after the stray hour; - closed 24 h 5 min after it.

It fails when the stray hour does not move the last-bad time.

• The unit comment in src/efficiency/causes.ts now lists "ratio" as well.
• The noteInstall import in src/checks/install.ts now sits with the other relative imports.

Why this goes ahead of the pipeline list: the issue belongs to the Maintainers epic #7553 and was opened because of #7541: the npm re-download (~30 GiB a day) went unnoticed until someone measured network bytes and read the caches by hand. Nothing else on the forge watches costs by cause, and the code is already written and reviewed. Whether to merge it now or hold it until after #6534, #6611 and #5276 is the owner's call; holding it costs only the wait.

Preview: /api/v1/health on the preview reports commit 7e54c3a, the commit before this round. I could not confirm that /api/v1/maintenance/runs lists efficiency-watcher. That endpoint answers only a forge admin, and my token is not an admin account in the preview's own database, so it returns unauthorized. An admin of the preview can check it there. Locally the duty is registered and runs in test/efficiency-runner.test.ts.

bun scripts/gate.ts, bun x tsc --noEmit and bun test test/efficiency-*.test.ts (23 tests) all pass.

To try it: run bun test test/efficiency-*.test.ts. On a forge, an admin reads GET /api/v1/maintenance/runs and sees the duty's hourly pass. Filed issues land in the repository named by FORGE_REPO.

🤖 Generated with Claude Code

The efficiency watcher is built and pushed, as three commits on this branch. The gate, tsc --noEmit and the 35 efficiency and maintain tests pass. I did not run the full suite; the forge's check does that on push.

What changed

• Duty: efficiency-watcher is a new maintainer duty, registered in src/maintain/registry.ts. Its code is in src/efficiency/: baseline, causes, judge, finding, store, readings, installs and watch.
• Causes read hourly: npm registry bytes, other egress bytes (image pulls, git, apps), CPU-seconds, and install cache hit rate.
• Baseline: the median of the same hour over the last 7 days.
• When it files: a cost files when it stays at 2x its baseline for 2 hours. A falling hit rate files when it is at or under half its baseline for 2 hours. Some causes also file at once on an absolute ceiling.
• Floors: a floor stops a near-zero baseline from counting as a doubling.
• Issues: one issue per cause. It names the cause, the number, the baseline and the code path that starts the cost.
• Comments and closing: while the cost stands it adds one comment per hour. It closes the issue with a note once the cost has been back under for 24 hours. Two readings in one hour keep the worse one.
• When nothing can be filed: if FORGE_REPO is unset or names no repository, it still reports the findings and says why it filed nothing.
• Board source: the samples are a source in src/boards/sources.ts, so a board can chart them. There is a migration, 20261111110000-efficiency, with its pin.
• Tests: test/efficiency-baseline, -double, -dedupe and -close-when-clear are the four the issue names. I added -hit-rate and -runner. The double test includes a replay of the #7541 series that files within 3 hours of the first bad hour, and a flat series that files nothing.
• Docs: docs/features/maintain.md describes the duty.

Not done

• Per-run CPU and peak memory are not sampled; CPU is read per hour for the whole machine.
• Image-pull and git bytes are not split out; they sit together in the "other egress" cause.
• Bytes per check, gate or preview run are not measured.
• The hit rate is only for the install cache; the check impact cache is not read.
• #7546's registry-bytes number is read where it already exists, not rebuilt.

Try it

• bun test test/efficiency-*.test.ts runs the efficiency tests.
• To see the duty in the app, run the efficiency-watcher duty from the maintainer runner. It needs FORGE_REPO set to an owner/name on this forge.