fix(cli): let check deadline honour --timeout and an env override - #5558

What

hyperframes check's total deadline now honours --timeout and can be raised with HYPERFRAMES_CHECK_DEADLINE_MS. The error says what the deadline was and how to raise it:

Check did not finish within its 120s deadline (raise with HYPERFRAMES_CHECK_DEADLINE_MS=<ms>, or --timeout <ms> for a slow-loading composition).

The <file>: its script did not finish… variant carries the same value and hint.

Why

#5537 added a fixed 120s clock that starts at browser readiness and covers navigation, render-ready, fonts, every sample and the --snapshots finding crops. --timeout only feeds the navigation and render-ready waits inside that clock, so raising it could not help: a large value let readiness alone use up the 120s. Since 0.8.153, heavy or slow-loading compositions fail with check_runtime_failure: Check did not finish within its deadline. and nothing can raise the limit. Before #5537 these checks completed.

Four field reports (win32 ×3, darwin ×1):

• an 86s portrait comp with --timeout 90000 --snapshots fails before any sample: https://slack.com/archives/C0BGC335AQY/p1791907900628219
• --timeout 180000 still hits the deadline: https://slack.com/archives/C0BGC335AQY/p1791908575285679
• a 5-min 1080p30 film with 16 sub-compositions fails even with a single --at, and each half passes alone in about 110s, so loading the comp already takes close to 120s: https://slack.com/archives/C0BGC335AQY/p1791913622028389
• https://slack.com/archives/C0BGC335AQY/p1791911799361359

Related work

Refs PRINFRA-2097 (https://linear.app/heygen/issue/PRINFRA-2097/). Follows up #5537 and keeps its guarantee: a composition whose script never finishes still makes check exit non-zero in bounded time.

How

resolveCheckDeadlineMs(options, env) in checkDeadline.ts, called once in runCheckPipeline:

base     = HYPERFRAMES_CHECK_DEADLINE_MS (positive integer ms) ?? 120_000
waits    = 3 (navigation, render-ready, audio-metadata audit) + 2 if --snapshots (crop-session navigation + render-ready)
deadline = min(2^31 - 1, base + waits × max(0, timeout − 3000))

• The default run keeps 120s exactly. The extra time counts only the --timeout above its 3000ms default, which the 120s already absorbed. A test pins resolveCheckDeadlineMs(DEFAULT_CHECK_OPTIONS) to 120s, so changing the default without updating the formula fails.
• --timeout is never swallowed. Every wait it governs after the clock starts gets the full extra time it asked for. However large the flag gets, readiness cannot shrink the time left for sampling and crops. Examples: --timeout 180000 gives 651s, and --timeout 90000 --snapshots gives 555s.
• The env var sets the base, and --timeout is still added on top. One variable can raise or lower the budget, for example for a long film whose sampling alone takes more than 120s, and a large --timeout passed alongside it still counts. Invalid values (non-integer, zero, negative, 1.5e5, 90s) are ignored, which matches how PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS and HYPERFRAMES_VISION_TIMEOUT_MS are read.
• The result is capped at Node's maximum timer delay. Above that, setTimeout fires immediately, and an over-large value would turn into an instant failure.
• I didn't add a new CLI flag. --timeout plus one env var covers all the reports without widening check's flag surface.

The docs (docs/packages/cli.mdx check section), the hyperframes-cli skill reference and the --timeout help text now describe the deadline and the override.

Test plan

• Unit tests added/updated. checkDeadline.test.ts keeps all of fix(cli): bound checks of non-finishing compositions #5537's cases unchanged, including the single budget that a second start() (crop readiness) cannot reset. New cases cover: the default and small --timeout values stay at 120s; a large --timeout extends the deadline with and without --snapshots; the env override sets the base and --timeout still adds to it; invalid overrides are ignored; huge inputs clamp to a valid timer; the timer fires at the resolved value; and both message variants. check.test.ts is updated for the new message.
• Locally: vitest run src/utils/checkDeadline.test.ts src/commands/check.test.ts passes (106 tests), tsc --noEmit in packages/cli passes, and oxfmt --check is clean. checkBrowser.test.ts can't load in my local sandbox (No such built-in module: node:), and it fails the same way on unmodified main, so CI covers it.
• Manual testing performed. I didn't re-run the reporters' heavy compositions.
• Documentation updated
• Comments follow CONTRIBUTING.md "Comments"

— Via

🤖 Generated with Claude Code