Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(memory-pressure): keep a flapping kernel level from re-running the levers

review5b4337794648
diff --git a/CLAUDE.md b/CLAUDE.md
index e8ffa450f..6f5c81c5e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6696,10 +6696,13 @@ byte leg (`hostMemReader`) stays `null` on darwin and main's RSS never nears the
until this leg the renderer's reclaim levers never ran on a visible Mac window — the safety net #179
counted on was dead. `core/memory-pressure.ts` now samples `kern.memorystatus_vm_pressure_level`
(1 normal / 2 warn / 4 critical; async `sysctl` per 30 s tick, last landed value) and calls
-`onKernelPressure` once per ESCALATION (normal→warn, →critical). Measured lever effect (dev, 12
+`onKernelPressure` on an ESCALATION (normal→warn, →critical). Measured lever effect (dev, 12
hidden warm terminals): GPU footprint 331 → 152 MB, IOSurface 235 → 91 MB, all 12 re-granted on
pan-back. Three rules: never re-fire a HELD kernel level (the 60 s floor at a held WARN is #179's
-timed release and its pan-back flicker again); never feed the level through `hostMemReader` /
+timed release and its pan-back flicker again), and never let a FLAPPING one do the same: each fall
+to normal re-arms the leg, so a run at the same or a lower severity than the last one waits out
+`KERNEL_LEVER_GAP_MS` (10 min) and only an escalation above it (warning → critical) fires inside the
+gap; never feed the level through `hostMemReader` /
`MemInfo` (`planReap` shares it — that would be a new reaper trigger); a kernel CRITICAL runs the
levers only, no reaper sweep, until that step is measured on its own (#211). A failed read is no
information: it neither fires nor resets the held level.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 872200879..30b265bde 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1371,8 +1371,9 @@ bite most often:
every frame through React Flow's ResizeObserver).
- Work done per terminal on a project switch must be coalesced and on-screen-first.
- macOS memory pressure comes from the kernel's level (`onKernelPressure` in
- `core/memory-pressure.ts`), fired on escalations only. Never re-fire it on a held level, and
- never route it through `hostMemReader`/`MemInfo`: the session reaper shares that reader.
+ `core/memory-pressure.ts`), fired on escalations only, and at the same severity at most once per
+ `KERNEL_LEVER_GAP_MS` (a level flapping normal/warn re-arms it every fall). Never re-fire it on a
+ held level, and never route it through `hostMemReader`/`MemInfo`: the session reaper shares that reader.
- A terminal under the kanban board must not draw. CSS can't stop xterm; its render pause is
`terminal/board-render-pause.ts`. Every "is the board up" check includes the Omni board
(`isGlobalKanbanOpen()`), and the board never feeds the visibility verdict that drives
diff --git a/docs/session-memory.md b/docs/session-memory.md
index 810386818..16ca699d2 100644
--- a/docs/session-memory.md
+++ b/docs/session-memory.md
@@ -555,7 +555,9 @@ macOS (the ps path never runs on Linux)
rather than a byte watermark — the same capture showed 82% used with AM's pressure graph GREEN.
**Code DONE 2026-10-19** — a separate darwin kernel-level leg in `core/memory-pressure.ts`
(`onKernelPressure`): renderer levers on escalations into warn/critical only, never on a held
- level, never through `hostMemReader`, no reaper sweep on kernel CRITICAL yet (#211). Owed: a
+ level, at most once per `KERNEL_LEVER_GAP_MS` (10 min) at the same or a lower severity so a
+ flapping level does not re-run them, never through `hostMemReader`, no reaper sweep on kernel
+ CRITICAL yet (#211). Owed: a
firing log under induced pressure on a dev build (`memory_pressure -S -l warn`), plus the GPU
process `footprint` / IOSurface count before and 60 s after the lever run.
RE-VERIFIED independently 2026-08-12 (second session, shipping function imported via esbuild
diff --git a/src/core/memory-pressure.test.ts b/src/core/memory-pressure.test.ts
index 9ab3be7b9..1a3d19a78 100644
--- a/src/core/memory-pressure.test.ts
+++ b/src/core/memory-pressure.test.ts
@@ -4,6 +4,7 @@ import {
hostMemReader,
kernelPressureReader,
parseKernelPressureLevel,
+ KERNEL_LEVER_GAP_MS,
RE_FIRE_FLOOR_MS,
type KernelLevelExec,
type KernelPressureLevel
@@ -115,7 +116,8 @@ describe('memory pressure monitor: darwin kernel-level leg', () => {
vi.useFakeTimers()
const onKernel = vi.fn()
const onPressure = vi.fn()
- // The extra tick primed at start() consumes the first entry.
+ // The extra tick primed at start() consumes the first entry. The second normal -> warn lands
+ // seconds after the critical run, inside the gap and below its severity, so it runs nothing.
const m = createMemoryPressureMonitor({
...quiet,
onPressure,
@@ -124,12 +126,53 @@ describe('memory pressure monitor: darwin kernel-level leg', () => {
})
m.start()
vi.advanceTimersByTime(7000)
- expect(onKernel.mock.calls).toEqual([['warning'], ['critical'], ['warning']])
+ expect(onKernel.mock.calls).toEqual([['warning'], ['critical']])
expect(onPressure).not.toHaveBeenCalled()
m.stop()
vi.useRealTimers()
})
+ it('a level flapping normal/warn every tick runs the levers once per gap (#179: no timed release)', () => {
+ vi.useFakeTimers()
+ const onKernel = vi.fn()
+ let tick = 0
+ const m = createMemoryPressureMonitor({
+ ...quiet,
+ intervalMs: 30_000,
+ onPressure: vi.fn(),
+ // start() primes with 'normal'; every tick after it alternates warn, normal, warn, …
+ readKernelLevel: () => (tick++ % 2 === 1 ? 'warn' : 'normal'),
+ onKernelPressure: onKernel
+ })
+ m.start()
+ vi.advanceTimersByTime(10 * 60_000)
+ expect(onKernel).toHaveBeenCalledTimes(1)
+ // The gap bounds the rate; it does not switch the leg off. Past it, the next escalation runs.
+ vi.advanceTimersByTime(KERNEL_LEVER_GAP_MS)
+ expect(onKernel).toHaveBeenCalledTimes(2)
+ m.stop()
+ vi.useRealTimers()
+ })
+
+ it('an escalation ABOVE the last run fires at once, even inside the gap', () => {
+ vi.useFakeTimers()
+ const onKernel = vi.fn()
+ const m = createMemoryPressureMonitor({
+ ...quiet,
+ intervalMs: 30_000,
+ onPressure: vi.fn(),
+ readKernelLevel: script(['normal', 'warn', 'normal', 'warn', 'normal', 'critical', 'normal', 'critical']),
+ onKernelPressure: onKernel
+ })
+ m.start()
+ vi.advanceTimersByTime(7 * 30_000)
+ // warn runs; the second warn is inside the gap; critical outranks the last run (warning) and
+ // fires; the second critical is inside the gap at the same severity.
+ expect(onKernel.mock.calls).toEqual([['warning'], ['critical']])
+ m.stop()
+ vi.useRealTimers()
+ })
+
it('a HELD warn stays one lever run past the 60 s re-fire floor (#179: no timed release)', () => {
vi.useFakeTimers()
const onKernel = vi.fn()
diff --git a/src/core/memory-pressure.ts b/src/core/memory-pressure.ts
index ad4794ce6..87d8a3b21 100644
--- a/src/core/memory-pressure.ts
+++ b/src/core/memory-pressure.ts
@@ -15,7 +15,10 @@
// This leg is deliberately NOT part of check()/onPressure:
// - it fires on TRANSITIONS into warn/critical only, never on a held level. The 60 s re-fire
// floor above at a held WARN (which a Mac can sit in for hours) would be #179's timed release
-// again, pan-back flicker included;
+// again, pan-back flicker included. A level that FLAPS (normal, warn, normal, warn — the
+// audited Mac moved between 1 and 2) is the same timed release by another route, so a run at
+// the same or a lower severity as the last one also waits out KERNEL_LEVER_GAP_MS; only an
+// escalation above the last run's severity (warning → critical) fires inside the gap;
// - it never goes through hostMemReader/MemInfo, which the reaper's planReap shares — a kernel
// WARN must not become a byte watermark the reaper culls detached sessions on (#135/#136/#137);
// - it reports through its own callback, so a shell decides separately whether a kernel CRITICAL
@@ -31,6 +34,10 @@ export const PRESSURE_INTERVAL_MS = 30_000
export const RE_FIRE_FLOOR_MS = 60_000
export const SELF_RSS_WARN_MB = 4096
export const SELF_RSS_CRIT_MB = 8192
+/** Minimum time between two kernel-leg lever runs at the same or a lower severity. Each fall to
+ * `normal` re-arms the leg, so without it a level alternating normal/warn would release every
+ * hidden WebGL context and drop the parks about once a minute. */
+export const KERNEL_LEVER_GAP_MS = 10 * 60_000
/** macOS's own pressure level, as `kern.memorystatus_vm_pressure_level` reports it. */
export type KernelPressureLevel = 'normal' | 'warn' | 'critical'
@@ -113,8 +120,9 @@ export function createMemoryPressureMonitor(opts: {
/** The kernel-level reader; defaults to `kernelPressureReader()` (absent off darwin). `null`
* switches the leg off. */
readKernelLevel?: (() => KernelPressureLevel | null) | null
- /** Fired once per ESCALATION of the kernel level (normal→warn, →critical), never on a held or
- * falling level. No callback ⇒ the leg is not sampled at all. */
+ /** Fired on an ESCALATION of the kernel level (normal→warn, →critical), never on a held or
+ * falling level, and at the same or a lower severity than the last run only once
+ * KERNEL_LEVER_GAP_MS has passed since it. No callback ⇒ the leg is not sampled at all. */
onKernelPressure?: (s: PressureSeverity) => void
log?: (m: string) => void
}): MemoryPressureMonitor {
@@ -134,6 +142,9 @@ export function createMemoryPressureMonitor(opts: {
// Starting at `normal` is what makes a healthy Mac silent (no transition to report) and what
// makes a launch INTO an already-pressured machine fire once.
let kernelHeld: KernelPressureLevel = 'normal'
+ // The last kernel-leg lever run: when, and at which level. Only a run moves these.
+ let kernelRanAt: number | null = null
+ let kernelRanLevel: KernelPressureLevel = 'normal'
const check = (): PressureSeverity | null => {
const rss = selfRss()
@@ -158,6 +169,17 @@ export function createMemoryPressureMonitor(opts: {
// Escalations only. A falling level runs nothing: the levers already ran on the way up, and
// whatever has re-granted since is warmth the user just panned back to.
if (KERNEL_RANK[level] <= KERNEL_RANK[from]) return
+ const now = Date.now()
+ if (
+ kernelRanAt !== null &&
+ KERNEL_RANK[level] <= KERNEL_RANK[kernelRanLevel] &&
+ now - kernelRanAt < KERNEL_LEVER_GAP_MS
+ ) {
+ log(`[memory-pressure] kernel ${level}: levers ran ${Math.round((now - kernelRanAt) / 1000)} s ago, skipping`)
+ return
+ }
+ kernelRanAt = now
+ kernelRanLevel = level
const severity: PressureSeverity = level === 'critical' ? 'critical' : 'warning'
log(`[memory-pressure] kernel ${level}: running reclaim levers (${severity})`)
try {
diff --git a/src/main/index.ts b/src/main/index.ts
index 848e1ec4b..3aad4fc25 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3561,8 +3561,9 @@ app.whenReady().then(async () => {
// try/catch is the backstop, not the primary.
//
// The kernel leg (macOS only — absent elsewhere) is the one that actually fires there: the byte
- // leg is silent on darwin and main's RSS never nears 4 GB. It runs the renderer levers ONLY, once
- // per escalation of `kern.memorystatus_vm_pressure_level`; a kernel CRITICAL deliberately does
+ // leg is silent on darwin and main's RSS never nears 4 GB. It runs the renderer levers ONLY, on an
+ // escalation of `kern.memorystatus_vm_pressure_level` (at most once per KERNEL_LEVER_GAP_MS at
+ // the same severity, so a flapping level does not re-run them); a kernel CRITICAL deliberately does
// NOT sweep the reaper yet — that is a separate, separately measured step (#211).
createMemoryPressureMonitor({
onPressure: (severity) => {