fix(flow): in-page poll loop is unusable in a backgrounded tab

[lamemustafa]

Summary

docs/PORTAL_INTEGRATION_FINDINGS.md #24 records that a full-fiscal-year run can stall when the
GST Portal tab or its window is backgrounded. That entry states a symptom and a policy
response; it never recorded a cause. The product now instructs operators to keep the portal
foregrounded, and getRequiredGstTab() force-focuses the tab and its window, on the strength of an
undiagnosed stall.

See the correction comment below before acting on this issue. The measurement below is
sound; the causal claim it was filed with was not. Pack's primary path already waits
worker-side, and the in-page loop measured here is a one-shot fallback whose connection to the
recorded stall is unestablished.

What was measured

A standalone page — no extension, no portal, no session — running Pack's own loop shape in a tab
hidden from load and never once visible. Warm-up sleeps of 5,000ms each:

ticks 1-50:  ~6000ms each   (5000 requested + ~1s clamp -- mild background throttling)
tick 51:     60999ms
tick 52:     61001ms        (intensive throttling)

Fifty ticks at ~6s is ~300s, so the clamp went from 1s to 60s at almost exactly five minutes
hidden — the documented onset of Chrome's intensive throttling.

Then Pack's filter-selection loop, unchanged:

polls:   1
gaps:    [25876]
elapsed: 25876ms   against a 15000ms deadline

One attempt. The single setTimeout(250) returned 25.9 seconds later, by which point the
deadline had already passed.

Why this happens

src/connectors/gst/main-world-filed-returns-filter-selection.ts is injected world: "MAIN", so it
runs in the page's context and inherits the page's timer throttling. Its selectOption is a
wall-clock-bounded poll:

const filterTimeoutMs = 15_000;
const filterPollMs = 250;
while (Date.now() - startedAt < filterTimeoutMs) { ...; await sleep(filterPollMs); }

Under intensive throttling a page timer fires at most once per minute, so the first poll wait
outlives the whole 15s budget. There are five in-page setTimeout call sites in that file — two
poll waits and three 1s waits.

Extension service worker timers are not throttled this way. Some of Pack's waits are already
worker-side and unaffected (for example the settle delay in
src/connectors/gst/../background/filed-returns-single-period-flow.ts), so only the in-page loops
are exposed. The change is narrower than "move the waits to the worker".

What this would reclassify, if the loop is on the stalling path

Superseded in part — see the correction comment. Where this loop is reached, the outcome is a
deterministic failure rather than a stall: one synchronous attempt, then false. The five-minute
onset would explain why only long runs are affected.

Whether a stalling run reaches this loop at all is not established. It is a one-shot fallback,
and the primary path's waits are already worker-side and unthrottled.

Proposed fix

Worker-driven polling: the wait loop lives in the service worker, and each page check becomes a
discrete executeScript. No page modification, no new permission, no visibility spoofing. It is
also more MV3-correct independently, because a worker-owned loop survives worker death in a way an
in-page loop does not.

Explicitly not proposed: spoofing document.visibilityState / document.hidden. The repo's own
precedent is that instrumentation which alters behaviour becomes the bug, and it would not help
against cause 3 below in any case.

Hard ordering constraint

Tab pinning must land with this fix, not after it.

getRequiredGstTab() is called at two sites, both phase starts, neither a recovery path. Nothing
recovers a run by re-acquiring a tab. So if the pinned tab were closed mid-run, the second site
would re-acquire a different GST tab and carry on — the identity hazard itself, wearing the
costume of resilience. Pinning one tab id for the whole run and failing closed removes an
opportunity to be wrong rather than removing a mechanism.

This matters here specifically because background running is exactly when re-acquisition could grab
a different taxpayer's tab. Shipping unattended runs first would widen that window rather than
leave it as it is.

Three caveats that must travel with the numbers

1. Measured in an in-app Chromium browser on a localhost origin, not in the user's own Chrome
   profile.
2. It measures a plain page's timer domain, not a world: "MAIN" injection into the portal. Same
   throttling code path as far as we can tell, but that inference is a step and should be visible
   as one.
3. It does not rule out a second cause. If the portal also gates on visibilitychange, or
   enables a control through requestAnimationFrame — which Chrome does not schedule for hidden
   tabs regardless of what the page believes — then fixing the timers moves where the run fails
   rather than fixing it. rAF is the candidate that would vindicate the current design. Do not
   promise unattended runs until this is settled.

Warning for anyone re-running the measurement

Do not watch the tab while it runs. An earlier run of this probe was invalidated by exactly
that: warm-up ticks read ~6000ms, then jumped to ~5003ms — unthrottled — immediately after the page
was read over CDP to check progress. Observing the throttling lifts the throttling, and periodic
checks appear to reset Chrome's own hidden-and-idle clock.

That run would have reached its gate having never banked five uninterrupted minutes, produced a
healthy poll count, and reported the hypothesis falsified — the opposite of the truth, with
clean-looking numbers and nothing downstream looking wrong. For this class of measurement a human
who walks away is a safer instrument than an agent that checks in.

The run of record above was untouched from load until after the loop returned.

[lamemustafa]

Correction: this issue overstated the causal claim, and I am the one who overstated it

I filed this saying "the cause is now measured". That was wrong — or rather, it asserted something
the measurement does not carry. Tracing the call graph afterwards, which I should have done before
writing a causal claim into an issue, narrows it considerably.

What is still true

The measurement stands. An in-page poll loop of the shape in
main-world-filed-returns-filter-selection.ts is unusable in a tab hidden past five minutes: one
attempt, 25.9s for a 250ms wait, against a 15s deadline. Nothing about the numbers changes.

What is not established

That this loop is on the path of the stall recorded in PORTAL_INTEGRATION_FINDINGS.md #24.

Three things I checked afterwards:

1. src/entrypoints/content.ts contains no in-page timers at all — no setTimeout,
   setInterval, requestAnimationFrame, or MutationObserver. The primary path is
   message-driven, and its waiting is done worker-side through delay(getFlowStepSettleMs(...)),
   which is not throttled. So the main flow's waits are already where I was proposing to move
   them.

2. The main-world filter selection is a one-shot fallback, not the normal path.
   mainWorldFilterAttempted is declared at filed-returns-single-period-flow.ts:249, set at
   :355, and never reset. It fires only when the content-script path reports
   filed-return-filter-candidate-not-found. How often a real full-year run reaches it is unknown
   and unmeasured.

3. The only other in-page timer is portal-blob-shim.ts:265, a 20s generation timeout. Under
   throttling that timeout fires late, around 60s — which makes it more lenient, not less. It
   cannot produce a stall.

What this changes about the fix

"Move the wait loop to the service worker" is much narrower than I wrote, because most of Pack's
waits are already there. The remaining exposure is one fallback path, and fixing it is worth doing
on its own merits — a one-shot that cannot succeed in a hidden tab is a real defect — but it should
not be sold as the fix for the recorded stall until something establishes that runs actually stall
there.

The uncomfortable part

The portal's own JavaScript is throttled by exactly the same mechanism, and Pack cannot fix that.
If the portal re-renders a dependent dropdown or enables a control on its own timer, that timer is
clamped in a hidden tab whatever Pack does. That is not hypothesis (1) at all — it sits between (2)
and (3), and it is not addressable from our side.

So the honest ranking has moved. Pack's in-page loop is a confirmed defect with an unconfirmed
connection to the symptom; the portal's own timing is an unconfirmed cause with a much more direct
connection.

What would settle it

The live half of the original probe plan, which has not been run: background the tab mid-run and
record where it stops, with timestamps. A Pack timer that never fires and a portal control that
never becomes enabled look nothing alike. One run distinguishes them, and until it happens this
issue should be read as "here is a real defect we found while looking", not "here is the cause".

I have left the numbers and caveats above unchanged and edited only the causal framing. The
sequencing constraint about tab pinning is unaffected by any of this and still holds.

[lamemustafa]

A second live stall, with the signals captured this time

A full-year GSTR-3B run stopped with:

full-fiscal-year-run-needs-action, gstr-3b-detail-route, filed-returns-heading,
gstr-3b, search-action, detail-ready-step-limit-reached

Note what is absent: filed-return-durable-status-rejected. This is a different stall from the
earlier one, and it rules out the durable-metadata hypothesis for this case.

What the signals say

The flow got as far as the GSTR-3B detail route, saw the filed-returns heading, and performed the
search action. Then waitForDetailReadyThenTrigger exhausted its budget waiting for the detail page
to become ready.

The budget, from filed-returns-flow-runner-utils.ts:

export const FLOW_STEP_SETTLE_MS = 150;
export const MAX_GSTR3B_FLOW_STEPS = 12;

Twelve attempts, 150ms apart. Under two seconds of wall clock for the portal to render a filed
return detail view after a search.

Why this matters for this issue

The waits here are worker-side, so they are not throttled — that part of the earlier analysis
holds. But the budget is small enough that it does not need throttling to be exceeded: a portal that
takes longer than about two seconds to paint the detail view exhausts it on a foregrounded tab.

That reframes the recorded symptom. A run that "stalls" may simply be a run that ran out of a very
tight budget, and the correlation with backgrounding may be a correlation with slowness rather than
with hidden-tab throttling specifically — background tabs get less CPU and slower network scheduling
whatever happens to timers.

Two things follow:

1. The foreground requirement may be a workaround for a budget that is too tight, not for a timer
   domain problem at all. That is a third hypothesis and it was not on the original list.
2. The backgrounding diagnostic in this issue is still the thing that separates them, and it is still
   unrun. But its discriminator needs extending: alongside "was the control enabled or disabled", it
   now matters how long the portal took, because a portal that is merely slow and a portal that is
   blocked look identical at twelve attempts.

Not proposing a number

Raising MAX_GSTR3B_FLOW_STEPS would probably make this particular run succeed, and that is exactly
why it should not be done from one observation. A budget chosen to survive one slow afternoon is a
budget chosen from noise. What is needed first is a measurement of how long the detail view actually
takes to become ready across several runs, foreground and background.

Reproduced

Twice today, both on full-year GSTR-3B. The first cleared with "Cancel and reset"; the run state was
discarded with it, so that instance cannot be diagnosed retrospectively.