Skip to content

perf(website): stop polling the gateway from a hidden tab - #37549

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
crew/kiro-crew-rust/pause-hidden-polls
Nov 15, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
crew/kiro-crew-rust/pause-hidden-polls

Conversation

@buluoray

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Task Runner or Worlds tab that nobody is looking at stops asking the gateway for data, and catches up the moment it is shown again.

Five timers kept reading the gateway from a hidden tab. In a stubbed dashboard, with the page told it is hidden, one minute of each page on main sends:

Page left in a hidden tab Requests per minute on main
Task Runner (/projects) 20 (GET /api/taskrunner every 3 s)
Worlds popout (/worlds-popout) 44 (GET /api/spawn every 3 s, GET /api/chat/slots and GET /api/crons every 5 s)

The chat page does not have this problem: it sends 0 requests while hidden, because its polls run through React Query, which pauses a hidden page.

Why it matters

People leave these pages open in a background tab for hours. Each such tab costs the gateway 20 to 44 requests a minute and wakes the tab's main thread for every answer, for a screen nobody sees. Each read also takes one of the browser's connections to the gateway.

Not a goal

  • Moving these pages to React Query. The reads and their state stay as they are; only the timer changes.
  • Changing how often a visible page reads.
  • useDashboardHealthProbe. It runs only while the gateway is unreachable, and a hidden tab still needs to reconnect.
  • Polls that already check visibility (presence, patrol, workflow heal, UI prefs flush).

What changed (motivation → approach → change)

A hidden page shows nothing, so a read it makes is wasted. pollWhileVisible(tick, ms) in website/src/lib/pollWhileVisible.ts repeats tick only while document.visibilityState is not hidden. When the page is shown again it runs tick once at once and restarts the cadence from there.

Five sites use it in place of their own timer:

Site Read
website/src/pages/ProjectsPage.tsx Task Runner runs, 3 s
website/src/pages/WorldsPopout.tsx session list, 5 s
website/src/hooks/useAgentSync.ts crons 5 s and subagents 3 s, for the Worlds page and its popout
website/src/hooks/useSceneInteraction.tsx the Worlds mini thread, 2 s
website/src/components/WebPreviewPanel.tsx the web preview's liveness probe, 5 s

The first read on mount and the cadence while visible are unchanged. useAgentSync used a setTimeout chain that armed the next read after each answer. It now ticks on an interval and skips a tick while the previous read of the same kind is still out, so a slow answer is still never overtaken.

Measurements

All numbers are mine, from one shared Linux host. The real built dashboard is served on 127.0.0.1; /api is answered by scripts/lib/stub-dashboard-api.mjs, and the websocket sends a status frame every 5 s as a live gateway does. Headless Chromium never reports a tab as hidden, so the page is told it is: document.visibilityState and document.hidden are overridden and visibilitychange is dispatched. The browser's own timer throttling for hidden tabs is therefore not part of these numbers. Each window is 60 s. The counts are requests that reached the server.

Before: main @ 4c530d0. After: this head.

Page Visible, before Visible, after Hidden, before Hidden, after
Task Runner 36 36 20 0
Worlds popout 44 44 44 0

On return both pages read at once: Task Runner sends GET /api/taskrunner, the popout sends GET /api/crons, GET /api/spawn and GET /api/chat/slots within the first second. Both pages rendered before counting (the Task Runner header and empty state, the popout's scene tabs), with no page error.

Not measured in a browser: the Worlds mini thread and the web preview probe (covered by the helper's unit test only), the embedded Worlds page (it shares useAgentSync with the popout), main-thread time (the two runs were taken at different host load), and a real hidden tab with the browser's timer throttling.

Backwards compatibility

Compatible: a visible page reads on the same cadence as before, and a page that comes back reads at once, so no screen shows older data than it did.

Removes nothing: no read, key or function is removed; a hidden page only stops repeating reads it would throw away.

Tests

  • website/src/lib/pollWhileVisible.test.ts: ticks on the cadence while visible and leaves the first tick to the caller; no tick and no timer while hidden; one tick at once on return, then the cadence from there; a page that opens hidden starts when first shown; a repeated visibility event adds no tick and no timer; stop clears the timer and the listener.
  • website/src/test/ProjectsPage.test.tsx: the Task Runner page reads its runs every 3 s, sends nothing for 60 s while hidden, reads once when shown again and resumes.
  • Ran: vitest run on those two files plus the WorldsPopout, useAgentSync*, UseSceneInteractionCoverage and WebPreviewPanel suites (10 files, 274 tests, all pass); tsc -p tsconfig.app.json clean; eslint on the changed files clean; comment-history, brand and line-cap gates pass.
  • The new Task Runner test fails on main (the page keeps reading while hidden).
  • Proof: not provable -- frontend test (prove.py runs Python only)

Manual verification

The request counts above, taken from the built dashboard in Chromium before and after. Not verified by hand: the web preview panel with a dev server that stops while the tab is hidden.

Screenshots / video

Why no screenshot: only timers change; a visible page renders and reads exactly as before.

Related Issues

N/A. Found in the Chrome modern-web-guidance review of the dashboard (efficient-background-processing).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 15, 2026 07:20
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 728183d589edbfe406b3a1dbe05334c10481907f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The diff changes only how often five hidden-tab polls run. It adds or changes no control, label, string or rendered state, so the missing blind read leaves no evidence gap.

[UX-REVIEWED] 728183d

Description read

[DESCRIPTION-READ] 1328407d9560be3b160a9e1fe2ddbbb144a58673d36dfd0febc2bdf22d5a226b

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 728183d589edbfe406b3a1dbe05334c10481907f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change targets a real cost, the fix is small and easy to revert, and it removes nothing.

Notes

  • lib/pollRule.ts already exports documentVisible (it treats a missing document as visible). pollWhileVisible writes its own document.visibilityState check instead. Importing the existing predicate would keep one definition of "visible" across the two polling helpers.

[DESIGN-REVIEWED] 728183d

Description read

[DESCRIPTION-READ] 7b176c272d44390399abc9afa017ac7782473799fe83dde8f554b84254c87edc

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 728183d589edbfe406b3a1dbe05334c10481907f — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The helper is new, and every item is a timer swap that removes measured hidden-tab requests. The web-preview probe falls outside the frozen Goal, and the same pattern still runs at unfixed sites.

Notes

  • Item 5 — oversized: the Goal is "A Task Runner or Worlds tab that nobody is looking at stops asking the gateway". WebPreviewPanel.tsx's liveness probe is neither of those, and the description says it was "Not measured in a browser". Subtraction: revert the useLivenessProbe hunk to setInterval and keep the PR to the two pages in the Goal.
  • Item 6 — symptom-level: I grepped setInterval( together with api.|fetch|load|poll|refresh and found at least 8 polls that still read while hidden. They are pages/chat/SubagentProgressBar.tsx, pages/overview/VectorMemoryCard.tsx, pages/knowledge/KnowledgeGraph.tsx, apps/crew-companion/{CrewCompanionPage,panel,pet}.tsx, apps/mochi/panel/MochiInstances.tsx and apps/md-notebook/useMdNotebookPageState.ts. The Goal limits this PR to two pages, so the rest is deferred, not demanded.

What this change ships

Inventory (7 items) — 5 justified

Intent: a background Task Runner or Worlds tab stops loading the gateway and catches up when shown again. This is a FIX (perf).

  1. Task Runner page stops reading /api/taskrunner while hidden, reads once on return — justified
  2. Worlds popout stops reading the session list while hidden — justified
  3. Worlds cron/subagent polls pause while hidden; cadence now runs from each tick's start, skipping a tick while the last read is still out — justified
  4. Worlds mini thread stops its 2 s read while hidden — justified
  5. Web preview liveness probe pauses while hidden — oversized (outside the Goal's two pages)
  6. Other gateway-reading setInterval polls are left unchanged — symptom-level (8 unfixed sites)
  7. New public helper pollWhileVisible in lib/ (5 consumers; not a duplicate of the React Query–bound lib/pollRule.ts or the singleton useSecondClock) — justified

[FIRST-PRINCIPLES-REVIEWED] 728183d

Description read

[DESCRIPTION-READ] 9889336589d166dd074f3b01bcde34ac750ebf9ee8a48c40806841f19fe1dcfa

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 728183d589edbfe406b3a1dbe05334c10481907f — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 728183d

Verdict parsed from the review's SHA-scoped output markers for commit 728183d589edbfe406b3a1dbe05334c10481907f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 728183d589edbfe406b3a1dbe05334c10481907f false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 728183d589edbfe406b3a1dbe05334c10481907f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 728183d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 728183d589edbfe406b3a1dbe05334c10481907f false-positive: <reason, 20 to 500 characters>

@buluoray

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 6) is red on head 6755609 with three test/metrics/test_kiro_export_destination.py::TestOffOffer failures. This PR changes no backend file. The same tests are red on main: #37546 tracks it and #37545 is the open fix. Waiting for that fix to merge, then rebasing; no rerun and no override for this red.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates an 8% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

The PR swaps five gateway-polling timers for a small helper, pollWhileVisible, that pauses while the tab is hidden and reads once when it is shown again. The helper is correct: it starts no timer when the page opens hidden, a repeated visibility event adds no timer, and stop removes the timer and the listener. Its unit tests cover these cases. The call sites keep the first read on mount and the visible cadence. ProjectsPage's load already guards against overlapping reads. Auto-run doesn't depend on the background poll, because the plan request is synchronous and doPlan reads the runs itself. useAgentSync moves from a setTimeout chain to an interval that skips a tick while the previous read of the same kind is still out, so a slow answer is still never overtaken. The new ProjectsPage test checks the hidden-tab behaviour. I found no regression, data risk or trust-boundary change.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 728183d589 · 183 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

…Worlds tab

Five timers kept reading the gateway from a tab nobody was looking at:
the Task Runner page (runs, every 3 s), the Worlds page and its popout
(sessions and crons every 5 s, subagents every 3 s), the Worlds mini
thread (every 2 s) and the web preview's liveness probe (every 5 s).

pollWhileVisible (website/src/lib/pollWhileVisible.ts) repeats a tick
only while document.visibilityState is not "hidden". When the page is
shown again it ticks once at once and restarts the cadence. The five
sites use it in place of their own setInterval or setTimeout chain. The
first read on mount and the cadence while visible are unchanged.

useAgentSync used a setTimeout chain that waited for each answer before
arming the next read. It now ticks on an interval and skips a tick
while the previous read of the same kind is still out, so a slow answer
is still never overtaken.
@buluoray
buluoray force-pushed the crew/kiro-crew-rust/pause-hidden-polls branch from 6755609 to 728183d Compare November 15, 2026 08:40
@buluoray

Copy link
Copy Markdown
Contributor Author

Rebased onto main @ 2e56b3b, which carries #37545 (the fix for the red TestOffOffer tests). New head 728183d, same change; CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 15, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 15, 2026 10:18

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. On this head the review read the full diff (8 files under website/src). It confirmed that pollWhileVisible starts no timer on a page that opens hidden, ticks once and starts one interval when the page is shown again, and removes its listener on stop. Planning on ProjectsPage still reads status directly, so a hidden tab does not stall an auto-run. The fake-timer tests restore real timers and never sleep. PR Readiness is green.

Done well: each helper test pins one branch, and the ProjectsPage test checks exact call counts through visible, hidden and shown-again phases.

Optional:

  • useAgentSync now polls on a fixed interval with busy guards. Before, it waited for each answer and then scheduled the next read. So a visible Worlds page reads more often when the gateway is slow (a 2.5 s answer takes the gap from about 5.5 s to 3 s). You could gate only the re-arm on visibility, or change the body to say the visible cadence is now fixed-rate.
  • The WebPreviewPanel change probes a dev-server URL on the chat side panel, not the gateway. That is outside the Goal's two pages, so you could drop that hunk.
  • The new cronBusy/spawnBusy guards have no test. One fake-timer test with a pending api.crons promise would pin them. Separately, documentVisible in lib/pollRule.ts already covers the helper's inline visibility check.

@KiroCrewCaptain
KiroCrewCaptain merged commit c031c43 into main Nov 15, 2026
99 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the crew/kiro-crew-rust/pause-hidden-polls branch November 15, 2026 10:18
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026
KiroCrewCaptain added a commit to KiroCrewCaptain/kirocrew-app-agent-worlds that referenced this pull request Nov 17, 2026
Two changes landed on the built-in's page after the port base
33979525d8:

- kirodotdev/KiroCrew#37549: the cron and subagent polls and the mini
  thread's 2-second refresh run only while the page is visible, tick
  once when it is shown again, and a cron or subagent read is skipped
  while the previous one is still out.
- kirodotdev/KiroCrew#38097: the collapse toggle of the page and the
  pop-out draws a lucide chevron instead of a triangle glyph.

PORTING.md lists both, and the committed bundle is rebuilt.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants