perf(desktop): stop idle-session event-health polling from re-rendering the whole shell

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.

[Astro-Han]

Summary

useSessionEventHealthPolling re-rendered the whole AppShell every 5s for the entire lifetime of any open session, idle or not — the only periodic work the app did while idle, and it changed nothing visible.

Four commits, one root cause:

1. Gate the polling. Once a session no longer expects an event stream there is nothing to observe: deriveSessionEventStreamStatus short-circuits to closed and shouldRefreshStaleSessionEventStream never fires. The interval and the visibilitychange listener are now gated on sessionExpectsEventStream.
2. Take health out of rendered state.sessionEventHealthBySession lived in AppShellSessionUiState, whose only purpose is to force a render. Nothing renders it — the sole reader is the polling effect via sessionEventHealthBySessionRef. It now lives in a controller-owned ref, so neither the probes nor the per-SessionEvent writes (app-shell-effects.ts:380, one extra full render per streamed event) notify React. setSessionEventHealthBySession keeps its updater signature, so all four call sites are untouched; clearSessionUiState drops the session from the ref alongside the rendered maps.
3. Drop the probe the gate left behind. The gate initially sat after a one-off evaluate(), so settling into idle still wrote one snapshot. That write cannot do anything — expected is false on this path, and neither status nor staleSince has a renderer consumer (the sidebar's staleSessionIds comes from stale-sessions.ts, an unrelated backend/slug classifier). markSessionEventStreamClosed already records the closed stream when the subscription goes away, so an idle session now costs nothing at all.
4. Comment and type cleanup left over from step 2.

Gating alone would have fixed the idle symptom, but only step 2 removes the per-event renders during a stream. Note that "skip unchanged writes" is not a valid alternative to either: the ref is only synced on write, so skipping writes would strand refreshRequestedAt and turn the 10s refresh cooldown into a refresh every tick.

Closes#1979

Verification

• npm --workspace apps/desktop run test:dist — 1348 pass, 0 fail.
• npm --workspace apps/desktop run typecheck — clean (preload, main, renderer, storybook).
• npm run format / npm run lint — clean.
• npm --workspace apps/desktop run e2e — 58 passed, including session-health-notice.spec.ts.

New coverage in app-shell-effect-stability-contract.test.ts, driven by a fake clock added to the existing fake DOM (observable window.setInterval / document.addEventListener, controllable Date.now):

• an idle active session arms no interval, registers no visibilitychange listener, and writes nothing at all — before or after the clock advances;
• a session going active → running → active re-arms and then disarms both the interval and the listener;
• a running session goes stale past the threshold, refreshes sessions and messages exactly once, and re-probes when the window becomes visible again.

Each was verified by mutation, not just by passing: removing the gate, moving the gate back after evaluate, making health writes notify again, dropping the ref cleanup in clearSessionUiState, and no-oping the interval callback each turn the corresponding test red. The round-trip case specifically covers the one failure mode this gate introduces — a session that starts running but never re-arms; shrinking the dep array to [activeId] leaves every other case green and fails only that one.

Not run: no screenshot or Storybook evidence — this PR removes renders and changes no pixels.

Review focus

clearSessionUiState now mutates the health ref in addition to replaceState. That is the one place where the ref's lifecycle could drift from the rendered maps, and it is covered by drops event-stream health along with the rest of a cleared session.

Known pre-existing behavior, not addressed here

If a session sits idle past the 15s threshold and then starts running before a fresh SessionEvent or sessions:changed observation reaches the renderer, the first evaluate reads stale observation timestamps, derives stale, and fires one extra refresh. The inputs to that first evaluate are bit-identical before and after this PR — evaluateSessionEventStreamSnapshot never advances subscribedAt / lastEventAt / lastChangedAt, so the idle ticks this PR removes never affected it. The refresh is idempotent and self-healing. Out of scope; worth a separate issue if it ever shows up in practice.

Related

• perf(desktop): AppShell subscribes to all session UI state at one granularity, so every stream token re-renders the whole shell #1985 — the other half of the same root cause: AppShell subscribes to all session UI state at a single granularity, so any write to a rendered map still re-renders the whole shell. Deliberately out of scope here.