[helen]

Summary

• Bound reflow viewport resize, overflow evaluation, and restoration to five seconds each. The finding callback has a separate 35-second budget to accommodate the screenshot library's existing 30-second timeout plus recording headroom.
• Propagate incomplete reflow checks with operation-specific errors, original failure causes, cleanup context, and unsafe-page metadata. Attempt original viewport restoration without an unbounded recovery loop.
• Preserve existing overflow tolerance and finding content, and fail without resizing when the original viewport cannot be captured.
• Document cooperative budgets and existing caller behavior in PLUGINS.md.

Relates to #303

Scope split

Per user direction, configurable caller failure policy is in independent draft PR #306. Both drafts target main; neither is stacked. This PR has no production changes to findForUrl or the core scanner: existing logging and partial-result behavior is preserved. A caller integration regression verifies that behavior when reflow reports an error.

Issue #303 was updated to align acceptance criteria with the selected policy. The companion PR adds plugin_failure_policy, defaulting to log-and-continue; selecting abort stops incomplete plugin work before findings publication. Neither default logging nor this plugin-local patch guarantees complete coverage. Both PRs use non-closing issue references so #303 is not closed by only one half of the split.

Verification

• npx --no-install vitest run .github/actions/find/tests/reflowScan.test.ts .github/actions/find/tests/findForUrl.test.ts .github/actions/find/tests/index.test.ts — 41 tests passed after the scope split.
• Reflow tests cover successful overflow/no-overflow, rejecting and non-returning resize/evaluation/finding/restoration, original-error preservation, absent viewport, and a healthy 31-second finding callback.
• npm run build --prefix .github/actions/find passed after the split.
• Strict standalone TypeScript checking passed for the dynamically loaded reflow plugin after the split.
• Real plugin-loader smoke tests passed for the 1px overflow threshold, viewport restoration, and preservation of original and cleanup errors.
• Prettier and ESLint passed for the reflow tests and caller integration test; git diff --check passed.

Dependency restoration was recovered via the configured registry proxy and offline installation of exact locked tarballs. No dependency manifests or lockfiles changed. The draft Test CI job is skipped; these results are local verification.

Limitations

Budgets are cooperative plugin-wait limits: up to 50 seconds with a finding callback, or 15 seconds without one, provided timers can run. They do not cancel in-flight Playwright operations or guarantee recovery from a blocked controller/event loop. Context/browser teardown is outside these budgets and can still hang; hard runtime recovery remains separate. Callbacks exceeding 35 seconds report an error rather than waiting indefinitely.

🤖 Assisted by Copilot