feat(cli): check --budget stops the whole check in time and reports what it found - #7245

What

hyperframes check --budget <ms|90s|8m> stops the whole check that long after the command starts, keeping 10 s back to write the report, and prints the report with what it found so far. A check_budget_reached error names the phase it was in and the seconds spent in each phase. Video copies get only what is left of the budget when that is under their own 2 minutes. Without --budget nothing changes.

Why

A host with its own time limit (Desktop allows a check 8 minutes from the moment it is asked) gets no report when that limit is hit. The CLI cannot answer the host's stop: on Windows the stop is taskkill /F, and a host that is stopping a command does not read what it printed. The check already ends itself after 2 minutes with no progress and reports its partial results then, but a check that keeps making progress runs until the host kills it. Only the CLI can stop in time on every OS, so it needs to be told how much time it has.

A 22 s project with live WebGL canvases and per-frame SVG displacement: the full check takes 71 s on a 32-core Linux box, 56 s of it in the craft pass, and each --range run takes 6 s because --range skips craft. On a slower Windows machine with time already spent in a queue, that can run past the host's limit.

How

CheckOptions.budget is { ms, stopAt }, with stopAt set when the flag is parsed, so time spent waiting for the project lock counts. CheckDeadline takes the budget beside its idle window and expires at stopAt with CheckBudgetError, through the same path an idle expiry takes: deadline.run rejects, the partial results the passes keep are merged into the report, and the browsers are closed. Its phase summary (where()) is shared with the idle message, whose text does not change. runBrowserCheck gives the copies min(2 minutes, remainingMs()). Crops are skipped once the deadline has expired, as finding frames already were, so an expiry is reported once; both read one isCheckExpiry test. The expiry promise is marked handled, so a budget that runs out before any step is waiting (a long wait for the project lock) is not an unhandled rejection. parseTimeoutMs takes the flag name for its warnings.

Test plan

• Unit tests added/updated:
  • fails without the fix: check.test.ts "--budget ends a check that is still within its idle window and keeps what its finished samples found": idle window 410 s, budget at 60 s; the report has check_budget_reached naming the overlap pass and per-phase seconds, ok: false, and the finished samples' layout finding. It fails with the budget not passed to the deadline.
  • fails without the fix: check.test.ts "--budget sets when the whole check stops, its report time kept back, counted from the command's start": --budget 8m gives ms 480000 and stopAt 470 s from the start; no flag gives none. It fails with the option not parsed.
  • fails without the fix: checkBrowser.test.ts "gives the copies only what is left of the check's --budget when that is under the copy budget": a copy that never finishes is stopped at 30 s with 30 s of budget left, not at 2 minutes. It fails with the copies given their full budget.
  • check.test.ts, checkBrowser.test.ts, checkDeadline.test.ts, timeoutArg.test.ts and checkPipeline.reportingProgress.test.ts (256) pass three runs in a row. tsc on the CLI: no errors.
• Manual testing performed: the built CLI, check --json --budget 40s on the 22 s WebGL and SVG project above (71 s without it): it exits at 30.9 s with the full JSON report, check_budget_reached "while running the overlap pass (craft frame at 10.375s)", seconds per phase, and the layout finding already made.
• Documentation updated (if applicable): the check flag table in docs/packages/cli.mdx.
• Comments follow CONTRIBUTING.md "Comments": no new comments, so no file's comment share rises. stopAt is a Date.now() time with the 10 s report margin already taken off; remainingMs() is undefined without a budget.

Not handled here: Desktop passing --budget with what is left of its own limit is the next change, on the Desktop side.

Size

About 55 lines of source in six files, about 110 of tests and one doc row. One change: check can be told its whole budget.