Repository navigation
fix(terminal): stop park-verdict oscillation remounting a pane at commit cadence (#15136) - #17009
Conversation
…15136) The verdict-flip pin was computed from flips on the rendered park verdict but applied only to the cold-park candidate set, so a loop driven by the worktree-level park prop or the activation-deferred branch kept remounting a pane at commit cadence while the pin silenced its own breadcrumb for 60s. Apply the pin to the rendered verdict via selectParkVerdictPinnedTabIds, and expire pins for every live tab so damping lapses on its own instead of re-arming forever.
📝 WalkthroughWalkthroughThe change adds Merge Risk: 🔵 Low · up to The PR applies damping to the final terminal parking verdict, preventing rapid pane remounts and reducing CPU and heat. It is mergeable with owner awareness of a bounded edge case where a backward clock adjustment could delay the 60-second pin expiry until another render occurs. 🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
Full details: Description checkExplanation The description gives detailed ELI5 context, root cause, implementation, linked issue, regression evidence, testing results, behavior impact, and limitations. However, it omits the required template sections and does not provide visual proof or the required N/A explanation for this behavior change. Resolution Add the missing template sections, especially Visual Proof with before-and-after evidence or an exact N/A justification. Complete the Testing, Notes, Review, Agent skill upstream boundary, and Checklist sections, including the required checkboxes and platform or CI coverage details.
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
src/renderer/src/components/terminal-pane/use-terminal-park-verdict-pin.ts (1)
1-15: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valuePlease consolidate the repeated park-verdict damping commentary into one concise invariant. Keep the regression test focused on the worktree-driver behavior and bounded result, and keep implementation comments focused on applying the pin to the merged rendered verdict and expiring it independently. Remove duplicated driver walkthroughs, field traces, and source-path history.
Source: Coding guidelines
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 6fb2bfee-ca99-4d96-bf77-7b5abafd0565
📒 Files selected for processing (6)
src/renderer/src/components/terminal-pane/terminal-park-verdict-flip-telemetry.test.tssrc/renderer/src/components/terminal-pane/terminal-park-verdict-flip-telemetry.tssrc/renderer/src/components/terminal-pane/terminal-park-verdict-worktree-driver-loop.test.tsxsrc/renderer/src/components/terminal-pane/use-terminal-park-verdict-pin.tssrc/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.test.tssrc/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.
…tablyai#15136) (stablyai#17009) The verdict-flip pin was computed from flips on the rendered park verdict but applied only to the cold-park candidate set, so a loop driven by the worktree-level park prop or the activation-deferred branch kept remounting a pane at commit cadence while the pin silenced its own breadcrumb for 60s. Apply the pin to the rendered verdict via selectParkVerdictPinnedTabIds, and expire pins for every live tab so damping lapses on its own instead of re-arming forever. (cherry picked from commit 50c8812)
…tablyai#15136) (stablyai#17009) The verdict-flip pin was computed from flips on the rendered park verdict but applied only to the cold-park candidate set, so a loop driven by the worktree-level park prop or the activation-deferred branch kept remounting a pane at commit cadence while the pin silenced its own breadcrumb for 60s. Apply the pin to the rendered verdict via selectParkVerdictPinnedTabIds, and expire pins for every live tab so damping lapses on its own instead of re-arming forever.
Fixes the CPU/heat half of #15136.
ELI5
Orca can put a terminal "to sleep" (park) when you can't see it, and wake it up when you look at it. Waking up is expensive — it rebuilds the terminal from scratch.
The rule for "is it safe to sleep?" is: can the background watchers still hear this terminal while its screen is gone? But the honest answer to that question changes depending on whether the screen is there right now. So: screen is up → "yes, safe to sleep" → screen goes away → "no, not safe" → screen comes back → "yes, safe" → … The terminal ends up flickering between asleep and awake dozens of times a second, and each flicker pays the full wake-up cost. That's the fan.
Someone already noticed this and added a brake: if a terminal flips 3 times in a second, hold it awake for 60 seconds. The brake was wired to only one of the several things that can order a terminal to sleep. When any of the other things was the one flapping, the brake pressed on nothing — but it still turned off the warning light for 60 seconds. So the terminal kept thrashing all session, silently, and the counter in the log ticked once a minute forever.
This PR wires the brake to the final answer instead of one input, so it actually stops the wheel it is supposed to stop.
Counters, before and after
The reporter's session (issue body):
terminal_replay_guard_wedged_releaseterminal_webgl_diagnostic/webgl-atlas-resetvisibility-resume,settled-reveal,tab-reveal)terminal_park_verdict_churnI reproduced the same signature in a local
main.trace.ndjson(25 h session, ~10 mounted pane managers). The hypothesis in the issue thread holds. Evidence:Two things fall straight out of that:
pinnedForMs. The pin engages, goes quiet, expires, and the very next flip (8–31 ms later) re-bursts.flips: 6crumbs prove flips kept accumulating while a pin was live. The existing damping was a treadmill: it silenced its own breadcrumb and stopped nothing.Atlas resets in the same log:
visibility-resume122 /settled-reveal122 — a perfect 1:1 pair, both reveal-shaped, exactly the reporter's reason mix. Every heavy reveal pays two registry-wide glyph-atlas wipes.The wedged replay guards line up too:
replayIntoTerminalarms a 10 s probe on reveal; if the pane is unmounted again before xterm drains, the write never parses and 10 s later releases aswedged. 2125 of them on one pane ≈ 2125 reveal→re-park cycles, at the code's own stated ~170 ms flat remount cost ≈ 6 minutes of pure remount CPU, plus the GC churn of allocating and destroying a multi-MB xterm buffer 2000 times. That is the heat. Park churn is the driver; the atlas resets and the wedged guards are symptoms, as @OrcaWin suspected.Measured on the deterministic repro added here (one park/reveal loop, one tab):
terminal_park_verdict_churngoes from ~1 crumb per 60 s with churn continuing underneath it to ~1 crumb per 60 s with the verdict actually held still, which drops the reveal-drivenwebgl-atlas-resetandterminal_replay_guard_wedged_releasetraffic with it.Root cause
The park verdict a tab renders is built here:
src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts:303The oscillation itself is the one this repo already documents in
terminal-cold-park-verdict-loop.test.tsx:5-9:canWatcherCoverParkedTerminalTabis re-derived from store and registry state that mounting/unmounting the very pane the verdict controls rewrites.Terminal.tsx:1035-1046runs that same predicate as a worktree-level park veto (worktreeTabsAreWatcherCovered), and that verdict arrives here ascoldParkTerminalPanes.The loop-breaker was
withholdUnparkableTerminalTabs(terminal-cold-park-withheld-tabs.ts:32), which filters onlycoldParkedTabIds— the right-hand side of that||. So:coldParkTerminalPanesshort-circuits past the pin entirely;activationDeferredMountTabIdsbranch;getParkVerdictUnparkPinUntilMs, which is also the only place a pin expires, is likewise reached only for cold-park candidates — so the record never re-arms cleanly, which is why the field trace shows a clean 60 s re-burst cadence forever instead of a settle.The module's own docstring said so out loud (
terminal-park-verdict-flip-telemetry.ts:6-10, before this PR): "the pin can only subtract from the cold-park candidate set … read a repeatingburstcrumb for one tab as 'damping did not reach the oscillating input'." The field data is exactly that repeating crumb.Fix
selectParkVerdictPinnedTabIds(terminal-park-verdict-flip-telemetry.ts:188) resolves and expires pins for every live tab, anduseTerminalParkVerdictPin(use-terminal-park-verdict-pin.ts) applies them as the last gate on the rendered verdict — the same quantity the flip telemetry observes. Whichever input oscillates, the loop is now broken, on the safe (mounted) side that the existing contract already chose.Why damping is the correct fix here, not a cop-out. The plant is inside the feedback path by design: parking's precondition is "will the byte watchers cover this tab once its pane is gone?", and the honest answer depends on state only the pane's presence establishes. You cannot delete that feedback without redesigning watcher coverage. What you can do — and what was already agreed as the mechanism — is break the loop at the actuator. This PR does not add a new threshold, raise an existing one, or debounce a symptom: it changes where the existing, already-derived brake is applied, from one input to the verdict, and makes it expire on its own. The atlas reset and the replay guard are deliberately untouched; they are downstream of the reveal.
Fix evidence
Test:
terminal-park-verdict-worktree-driver-loop.test.tsx. Single tab, soselectIdsBeyondHotRetainspares it via the last-active exemption and the cold-park set is provably empty —coldParkTerminalPanesis the only driver, which is exactly what the old pin could not reach.Reverted (
pinnedTabIds.size === 0→>= 0, i.e. the pin never reaches the rendered verdict):Restored: passes at 4 flips / 3 mounts / 6 renders.
Also added a direct unit case in
terminal-park-verdict-flip-telemetry.test.tsfor the property the old wiring broke — a pin must be selectable and expirable for a tab the cold-park selector never proposed.Checks
tscclean on all three configs (tsconfig.node.json,tsconfig.tc.cli.json,tsconfig.tc.web.json)oxlintclean on every changed file; nomax-linesdisable added (the new hook is a separate module precisely souse-terminal-tab-cold-parking.tsstays under the 300-line budget)vitest— 2179 files / 17 813 tests pass acrosssrc/renderer/src/components,src/renderer/src/lib/pane-manager,src/renderer/src/store/terminalssetTimeoutper live pin, armed off an absolute deadline and skipped when that deadline is unchanged, so a busy agent pane re-minting the tab model many times a second does not re-arm it. No polling added.Behaviour change worth knowing
A pinned tab now stays mounted even when the worktree-level verdict (including retention-budget force-park) says park. That is bounded to the 60 s pin window and only triggers after ≥3 verdict round-trips inside one second — which the policy's own hysteresis (30 s cold-park delay) says cannot happen honestly. Two existing assertions in
use-terminal-tab-cold-parking.test.tsdrove three park round-trips with frozen fake timers and so read as an oscillation; they now advance the clock past the burst window between transitions.What this does not fix, honestly
This stops the pane from remounting at commit cadence. It does not remove the self-referential coverage predicate that makes the loop possible in the first place —
canWatcherCoverParkedTerminalTabstill answers differently depending on whether the pane it gates is currently mounted, andTerminal.tsx's worktree-level use of it still has no damping of its own. I could not isolate, from static reading alone, exactly which term inside that predicate flips for the reporter's SSH panes; the trace records the flip, not the input. Making the churn breadcrumb carry the deciding input is the obvious follow-up, and is now much cheaper to act on because the pane is no longer thrashing while you read it.Closes the perf half of #15136.