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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(memory-pressure): keep a flapping kernel level from re-running the levers
review5b4337794648
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 theuntil this leg the renderer's reclaim levers never ran on a visible Mac window — the safety net #179counted 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, 12hidden warm terminals): GPU footprint 331 → 152 MB, IOSurface 235 → 91 MB, all 12 re-granted onpan-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 thelevers only, no reaper sweep, until that step is measured on its own (#211). A failed read is noinformation: it neither fires nor resets the held level.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 drivesdiff --git a/docs/session-memory.md b/docs/session-memory.mdindex 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: afiring log under induced pressure on a dev build (`memory_pressure -S -l warn`), plus the GPUprocess `footprint` / IOSurface count before and 60 s after the lever run.RE-VERIFIED independently 2026-08-12 (second session, shipping function imported via esbuilddiff --git a/src/core/memory-pressure.test.ts b/src/core/memory-pressure.test.tsindex 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.tsindex 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_000export const RE_FIRE_FLOOR_MS = 60_000export const SELF_RSS_WARN_MB = 4096export 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) => voidlog?: (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 = levelconst 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.tsindex 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) => {