[agegr]

Over HTTP/1.1 a browser opens at most six connections per origin, shared
by all its tabs. Every pi-web tab kept the selected session's agent event
stream open even while idle (the warm-session effect; the idle grace in
scheduleEventStreamClose() skips the selected session), plus the active
file tab's watch while the right panel was open. A few background tabs
filled the pool, so Settings loads and message sync queued in the browser
until one tab closed.

The selected session is now kept alive by the page, not by its stream.
Each page holds a liveness lease of its own (POST
/api/agent/[id]/lease?holder=, holdSessionLivenessLease(): one
per page and session, 90 s TTL), taken on selection and renewed every
30 s and on return, whether or not the stream is open. Its reply says what
is under way in the session, read from the wrapper without starting one or
resetting its idle timer: running (isRunning(): a prompt, a queued one, a
! command, a compaction), awaitingInput (an extension dialog waiting for
an answer) and subagentsActive (an unsettled subagent at any depth,
hasUnsettledSubagentRun()).

A visible page always keeps its stream. A page hidden for
HIDDEN_PAGE_GRACE_MS (30 s, hooks/usePageHidden.ts) ends the grace with a
lease request and closes the stream only if the reply shows nothing under
way (canReleaseHiddenEventStream()); a run, ! command, compaction or
dialog in the page keeps it without asking. No reply within 5 s, the
request queued behind a full pool, also releases; an error reply keeps
it and checks again next grace. While released and still hidden, a
renewal reply that shows activity opens the stream again
(sessionLeaseShowsActivity()), so a run another tab, a device or an
extension's timer starts there, and an extension dialog, still reach the
hidden page with the chime and browser notifications; it is let go again
a grace after the activity ends. The page's return reopens it at once.
Either way the session is read again with its state, applied as the mount
does (applyLoadedAgentState()); nothing is resent.

The stream no longer carries the lease, so dead streams are found by a
heartbeat watchdog: the server's 30 s heartbeat is a data event now (an
SSE comment never reaches EventSource), and AgentEventConnection
reconnects a ready stream silent for 75 s.

The file watch pauses after the same grace. On reconnect the viewers
compare the file's size and mtime (now in type=meta and type=read, the
pair the watch's change events carry) and reload only a changed file, so
coming back keeps a text file's Load more chunks and scroll position,
media playback and a PDF's place.

What a released page can still miss: a run that starts and settles
between two renewals plays no chime and shows no in-page notification
there; web push still announces its completion when subscribed. Terminal
streams are left alone: the server kills a shell that has had no listener
for two minutes. Feedback in the UI when requests are stuck is not
addressed.

Refs #1283

Trade-off to decide in review

The selected session is kept alive by the page, not by its stream: every page holds a liveness lease of its own (POST /api/agent/[id]/lease?holder=<page id>, one per page and session, 90 s TTL), renewed every 30 s whether or not the stream is open, so releasing a hidden page's stream no longer lets the idle wrapper be reaped. The renewal's reply says what is under way in the session (running, awaitingInput, subagentsActive, read from the wrapper without starting it or resetting its idle timer), and that one reply decides both ends of the release:

• A page hidden for 30 s closes its idle stream only when a lease reply shows nothing under way (no reply within 5 s also releases: the request is then queued behind a full pool).
• While released and still hidden, a renewal reply that shows activity opens the stream again, so a run started from another tab or device or by an extension's timer, and an extension dialog, still reach the hidden page with the chime and browser notifications. The stream is let go again a grace after the activity ends.

A visible page always keeps its stream. Dead streams are found by a heartbeat watchdog instead of the lease: the server's 30 s heartbeat is now a data event, and a ready stream silent for 75 s reconnects.

What is left: a run that starts and settles between two renewals (30 s apart; Chrome slows a page hidden for over 5 minutes to about one timer a minute) plays no chime and shows no in-page notification on the hidden page. Web push still announces its completion when subscribed. Before this PR every open tab held one idle stream (two with a file open), which is what fills the six-connection HTTP/1.1 pool.

Testing

• hooks/hidden-page-stream.test.mjs (real hook, mocked timers): a quick hide/show keeps the stream; a page hidden past the grace releases on an idle lease reply and reopens on return; the lease is renewed the whole time, with or without the stream; a running, awaiting-input or subagent reply keeps it and is checked again each grace; a reply that never comes releases after 5 s, no network releases, an error reply keeps it; a released hidden page reopens when a renewal shows a run, receives its completion, and lets go a grace after it settles; the same for an extension dialog; a pending dialog in the page keeps it without asking.
• app/api/agent/lease-route.integration.test.mjs: 400 without a holder; the reply reports an idle wrapper and the lease keeps it from being reaped; a lease for an unknown session never starts a wrapper.
• lib/agent-event-connection.test.mjs (heartbeat watchdog), lib/agent-event-stream.test.mjs (heartbeat as a data event, no lease on the stream), lib/session-liveness.test.mjs (per-page leases), lib/file-version.test.mjs, lib/subagent-runtime.test.mjs.
• tsc --noEmit, npm run lint, npm test 2820 / 0 fail on Node 24. Node 22 is left to CI for the last two commits.
• Chrome against an isolated dev server with PI_WEB_IDLE_TIMEOUT_MS=40000: heartbeats arrive while visible; hidden 34 s holds 0 streams and the wrapper stays alive; hidden 94 s (past the idle timeout) the wrapper is still alive, renewed every 30 s; visible again reopens the stream; 140 s after the tab closes the wrapper is reaped.
• Chrome, hidden and released page, another client runs a 60 s extension command in the session: the next renewal reports running: true, the stream reopens while still hidden, prompt_done reaches the page, and the stream is released again 30 s after the run. With a 20 s command that started and ended between two renewals, the hidden page did not reopen (the gap above).
• An unchanged text file is not re-read on return (only type=meta), from the first commit's check.
• Two independent reviews of the first commits found lost subagent-triggered runs, no grace, idle shown on return, the text viewer losing Load more, the idle check starving in a full pool, a window where a finished subagent's parent notice was not yet counted, and a stale git diff gutter after an unchanged reconnect; all fixed.

🤖 Generated with Claude Code

[wowayou]

Thanks for #1328. On the trade-off: I'm fine with it. Releasing only after 30 s hidden and a server-side idle check, re-reading the session on return, and never resending covers acceptance point 1 and the no-replay boundary. Web push still covers completion, which is what matters most for a background tab.

Review notes, none blocking:

• Treating an unanswered idle check as releasable is the right call, since a starved pool is exactly that case.
• Held leases expire on their own timer, so stale keys left in the holds map until the next holdSessionLivenessLease() call are harmless.
• Chrome throttles timers in long-hidden tabs to about once a minute. That still renews the 30 s lease well within the 90 s TTL. A frozen or discarded tab stops renewing, which behaves the same as a closed tab today.

Verified locally on 539e4cc: the PR's tests pass 44/44, tsc --noEmit is clean, the full npm test passes (4 plugin-update tests fail only with PI_OFFLINE=1 set in my env), and the branch merges cleanly onto main 628d6ac. I didn't run a browser smoke test.

Agree on keeping #1283 open for the stuck-request UI feedback.