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
import { describe, expect, it } from 'vitest'
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import {
planReap,
parseSessionList,
sessionBudgetConfig,
createSessionReaper,
hostUnderMemoryPressure,
readMemInfo,
type SessionInfo,
type SessionBudgetConfig
} from './session-budget'
const NOW = 1_753_000_000 // fixed epoch seconds for every test
const cfg = (over: Partial<SessionBudgetConfig> = {}): SessionBudgetConfig => ({
disabled: false,
minAvailableMb: 2048,
maxDetached: 48,
graceSec: 6 * 3600,
batchMax: 8,
swapFreeRatio: 0.2,
swapAvailRatio: 0.25,
psiFullAvg60: 10,
...over
})
/**
* An nt- session whose PANE has been silent for `idleH` hours, with `clients` attached.
*
* **`activitySec` is deliberately always FRESH (60 s old), no matter how long the session has been
* silent** — that is the shape every session on a live host has, because tmux bumps
* `#{session_activity}` on every client attach and nodeterm attaches constantly (measured: across
* 67 production sessions the OLDEST `session_activity` was 33 minutes, while the oldest
* `#{window_activity}` was 37 hours).
*
* Encoding it in the shared helper makes the whole suite a regression test for the clock: if this
* module ever goes back to gating on `activitySec`, nothing is ever past grace and every eligibility
* assertion below turns red at once. A helper that set both stamps to the same value would let that
* revert pass — the two clocks have to disagree here, because they disagree in production.
*/
const idle = (name: string, idleH: number, clients = 0): SessionInfo => ({
name,
clients,
activitySec: NOW - 60,
outputSec: NOW - idleH * 3600
})
const lowMem = { availableMb: 500, totalMb: 64_000 }
const okMem = { availableMb: 30_000, totalMb: 64_000 }
describe('planReap (pure policy)', () => {
it('under memory pressure, reaps the least-recently-active detached sessions first', () => {
const plan = planReap([idle('nt-old', 240), idle('nt-mid', 48), idle('nt-new', 7)], lowMem, NOW, cfg({ batchMax: 2 }))
expect(plan).toEqual(['nt-old', 'nt-mid'])
})
it('never reaps an attached session, no matter how idle', () => {
const plan = planReap([idle('nt-watched', 500, 1), idle('nt-idle', 500)], lowMem, NOW, cfg())
expect(plan).toEqual(['nt-idle'])
})
it('never reaps within the grace window, even under pressure', () => {
const plan = planReap([idle('nt-recent', 1), idle('nt-old', 100)], lowMem, NOW, cfg())
expect(plan).toEqual(['nt-old'])
})
it('ignores sessions not named nt-* (a user session on the same socket is untouchable)', () => {
const plan = planReap([idle('main', 500), idle('nt-x', 500)], lowMem, NOW, cfg())
expect(plan).toEqual(['nt-x'])
})
it('healthy memory + under cap → reaps nothing', () => {
const plan = planReap([idle('nt-a', 500), idle('nt-b', 500)], okMem, NOW, cfg())
expect(plan).toEqual([])
})
it('a FAILED memory read is not pressure (mem=null never triggers the watermark)', () => {
const plan = planReap([idle('nt-a', 500)], null, NOW, cfg())
expect(plan).toEqual([])
})
it('count cap is a backstop: excess detached sessions are reaped even with healthy memory', () => {
const sessions = Array.from({ length: 10 }, (_, i) => idle(`nt-s${i}`, 100 + i))
const plan = planReap(sessions, okMem, NOW, cfg({ maxDetached: 7 }))
// 10 detached, cap 7 → 3 oldest go (highest idle hours = oldest activity)
expect(plan).toEqual(['nt-s9', 'nt-s8', 'nt-s7'])
})
it('attached sessions do not count toward freeing the cap, but are never the ones killed', () => {
const sessions = [idle('nt-live', 500, 2), ...Array.from({ length: 5 }, (_, i) => idle(`nt-d${i}`, 100 + i))]
const plan = planReap(sessions, okMem, NOW, cfg({ maxDetached: 4 }))
expect(plan).toEqual(['nt-d4'])
})
it('combined triggers stay bounded by batchMax per sweep (gradual convergence)', () => {
const sessions = Array.from({ length: 30 }, (_, i) => idle(`nt-s${i}`, 100 + i))
const plan = planReap(sessions, lowMem, NOW, cfg({ maxDetached: 5, batchMax: 4 }))
expect(plan).toHaveLength(4)
})
it('disabled kill switch plans nothing', () => {
const plan = planReap([idle('nt-a', 500)], lowMem, NOW, cfg({ disabled: true }))
expect(plan).toEqual([])
})
it('pressure alone reaps at most batchMax even with many eligible', () => {
const sessions = Array.from({ length: 20 }, (_, i) => idle(`nt-s${i}`, 100 + i))
const plan = planReap(sessions, lowMem, NOW, cfg({ batchMax: 3 }))
expect(plan).toHaveLength(3)
})
// The 2026-08-11 profile: plenty of RAM, well under the detached cap, and the machine still
// could not open a terminal because it was out of pty DEVICES. Without an allowance of its own
// that reading plans nothing at all — the sweep the shell fires on critical pty pressure would
// be a no-op, which is exactly the bug this argument exists to close.
it('an external pressure reason earns the same allowance low memory does', () => {
const sessions = Array.from({ length: 20 }, (_, i) => idle(`nt-s${i}`, 100 + i))
expect(planReap(sessions, okMem, NOW, cfg({ batchMax: 3 }))).toHaveLength(0)
expect(planReap(sessions, okMem, NOW, cfg({ batchMax: 3 }), true)).toHaveLength(3)
})
it('external pressure widens NO safety gate: attached and in-grace sessions still live', () => {
const sessions = [idle('nt-watched', 500, 1), idle('nt-fresh', 1), idle('user-shell', 500)]
expect(planReap(sessions, okMem, NOW, cfg(), true)).toEqual([])
})
it('the kill switch still wins over an external pressure reason', () => {
const plan = planReap([idle('nt-a', 500)], okMem, NOW, cfg({ disabled: true }), true)
expect(plan).toEqual([])
})
})
describe('the two clocks (the measurement this whole change rests on)', () => {
// 2026-08-15, production host: `nt-term-msrblsui-9` had NO pane output for 18.1 hours while
// `session_activity` read 15 minutes, because nodeterm had just re-attached a client to it.
const realHostSession: SessionInfo = {
name: 'nt-term-msrblsui-9',
clients: 0,
activitySec: NOW - 15 * 60, // what tmux says: 15 minutes
outputSec: NOW - 18 * 3600 // what the pane says: 18 hours of silence
}
it('reaps a session tmux calls fresh when its pane has been silent past grace', () => {
expect(planReap([realHostSession], lowMem, NOW, cfg())).toEqual(['nt-term-msrblsui-9'])
})
it('SPARES a session tmux calls stale when its pane is actually producing output', () => {
// The mirror image, and the reason this is not merely "use the older number": a session whose
// client detached hours ago but whose agent is still printing must survive. Gating on
// `activitySec` would kill it.
const working: SessionInfo = {
name: 'nt-busy',
clients: 0,
activitySec: NOW - 40 * 3600, // no client has attached in nearly two days
outputSec: NOW - 30 // …but the pane wrote something 30 seconds ago
}
expect(planReap([working], lowMem, NOW, cfg())).toEqual([])
})
it('orders by silence, not by attach time', () => {
const a: SessionInfo = { name: 'nt-a', clients: 0, activitySec: NOW - 3600, outputSec: NOW - 10 * 3600 }
const b: SessionInfo = { name: 'nt-b', clients: 0, activitySec: NOW - 90000, outputSec: NOW - 40 * 3600 }
// `b` is the least-recently-ACTIVE by output and must die first, even though `a` looks older
// on the attach clock's ordering.
expect(planReap([a, b], lowMem, NOW, cfg({ batchMax: 1 }))).toEqual(['nt-b'])
})
})
describe('parseSessionList', () => {
it('parses names, CLIENT COUNTS, activity and OUTPUT time, skipping malformed lines', () => {
const out = parseSessionList(
'nt-a|0|1753000000|1752900000\nnt-b|2|1753000100|1753000100\n\njunk\nx|y|z|w\nnt-c|0|1753000000\n'
)
expect(out).toEqual([
{ name: 'nt-a', clients: 0, activitySec: 1_753_000_000, outputSec: 1_752_900_000 },
{ name: 'nt-b', clients: 2, activitySec: 1_753_000_100, outputSec: 1_753_000_100 }
])
// `nt-c` carried the OLD three-field shape. It is dropped rather than defaulted, so a format
// that ever regresses produces no candidates instead of candidates with a fabricated clock.
expect(out.map((s) => s.name)).not.toContain('nt-c')
})
it('rejects a row with MORE than four fields rather than parsing the first four', () => {
// The length check is pinned EXACTLY, as the original parser pinned its own. A row carrying an
// unexpected fifth field is a row in a format we do not understand, and the safe answer is to
// contribute no candidate rather than to trust four columns that happen to look plausible.
//
// Note the shape of this row: its first four fields are all individually VALID, so the numeric
// guards below cannot reject it. Only the exact-length check can — which is what makes this an
// assertion about that check rather than about the guards. (A row like `nt-a|b|0|1|2` proves
// nothing here: `Number('b')` is NaN and the client-count guard rejects it either way.)
expect(parseSessionList('nt-a|0|1753000000|1752900000|extra')).toEqual([])
expect(parseSessionList(`nt-ok|0|${NOW - 60}|${NOW - 40 * 3600}`)).toHaveLength(1)
})
it('reduces a multi-window session to ONE row holding its most recent output', () => {
// Verified against tmux: `list-windows -a` emits one line per window, and a two-window session
// carries two distinct `#{window_activity}` stamps. A session is silent only when ALL of its
// windows are, so the newest wins — and it must win regardless of which order they arrive in.
const newestLast = parseSessionList('nt-a|0|1753000000|1752900000\nnt-a|0|1753000000|1752999000')
const newestFirst = parseSessionList('nt-a|0|1753000000|1752999000\nnt-a|0|1753000000|1752900000')
expect(newestLast).toEqual([{ name: 'nt-a', clients: 0, activitySec: 1_753_000_000, outputSec: 1_752_999_000 }])
expect(newestFirst).toEqual(newestLast)
})
it('a session with a busy second window is NOT reaped for its quiet first one', () => {
// The behavioural consequence of the reduce, asserted through planReap rather than the parser:
// window 0 has been silent for 40 h, window 1 wrote a second ago.
const sessions = parseSessionList(
`nt-two|0|${NOW - 60}|${NOW - 40 * 3600}\nnt-two|0|${NOW - 60}|${NOW - 1}`
)
expect(planReap(sessions, lowMem, NOW, cfg())).toEqual([])
})
})
describe('hostUnderMemoryPressure', () => {
const c = cfg({ minAvailableMb: 6416 }) // 10% of a 64 GB host
// The live production reading, 2026-08-15: 12.6 GB available of 62.7 GB (well above the
// watermark), swap 73.9% consumed, PSI quiet. Nothing is wrong right now, so nothing may fire —
// this is the guard against a fix that simply reaps more.
const healthyToday = { availableMb: 13_481, totalMb: 64_158, swapTotalMb: 8192, swapFreeMb: 2140, psiFullAvg60: 0 }
// The reading this task was opened on: 10.5 GB available (16.7%), swap 84% consumed.
const swapSpent = { availableMb: 10_752, totalMb: 64_158, swapTotalMb: 8192, swapFreeMb: 1331, psiFullAvg60: 0 }
it('a failed read is never pressure', () => {
expect(hostUnderMemoryPressure(null, c)).toBe(false)
})
it('the available-memory watermark still fires on its own', () => {
expect(hostUnderMemoryPressure({ availableMb: 500, totalMb: 64_158 }, c)).toBe(true)
})
it("today's host — above the watermark, swap 74% spent, PSI quiet — is NOT pressure", () => {
expect(hostUnderMemoryPressure(healthyToday, c)).toBe(false)
})
it('swap 84% spent WITH low available memory IS pressure (the state the old reader called healthy)', () => {
expect(hostUnderMemoryPressure(swapSpent, c)).toBe(true)
// …and the old instrument, which is exactly `availableMb` against the watermark, says no.
expect(swapSpent.availableMb < c.minAvailableMb).toBe(false)
})
it('either half of the swap term alone is benign', () => {
// Swap spent, but memory is plentiful: cold pages parked in swap on a healthy host.
expect(hostUnderMemoryPressure({ ...swapSpent, availableMb: 40_000 }, c)).toBe(false)
// Memory lowish, but swap untouched: the reserve is still there.
expect(hostUnderMemoryPressure({ ...swapSpent, swapFreeMb: 8000 }, c)).toBe(false)
})
it('a host with NO swap configured never trips the swap term (0/0 is not exhaustion)', () => {
expect(hostUnderMemoryPressure({ ...swapSpent, swapTotalMb: 0, swapFreeMb: 0 }, c)).toBe(false)
})
it('absent swap fields are no signal, not zero', () => {
const { swapTotalMb: _t, swapFreeMb: _f, ...noSwap } = swapSpent
expect(hostUnderMemoryPressure(noSwap, c)).toBe(false)
})
it('HALF a swap reading is no signal either, in both directions', () => {
// `MemInfo` is a shared type and its swap pair is optional, so a caller that is not
// `parseMemInfoText` (the SSH leg, a future reader) can hand over one half. Neither half alone
// may be completed with a default: filling the missing TOTAL invents a denominator, and filling
// the missing FREE with 0 states that swap is exhausted. Both would make this term fire on a
// host nobody measured. Pinned explicitly because the arithmetic happens to yield NaN today —
// a guard that only works by accident of NaN is not a guard.
const { swapFreeMb: _f, ...totalOnly } = swapSpent
const { swapTotalMb: _t, ...freeOnly } = swapSpent
expect(hostUnderMemoryPressure(totalOnly, c)).toBe(false)
expect(hostUnderMemoryPressure(freeOnly, c)).toBe(false)
})
it('PSI full avg60 past the bar is pressure on its own; absent PSI is not', () => {
expect(hostUnderMemoryPressure({ availableMb: 40_000, totalMb: 64_158, psiFullAvg60: 25 }, c)).toBe(true)
expect(hostUnderMemoryPressure({ availableMb: 40_000, totalMb: 64_158, psiFullAvg60: 0 }, c)).toBe(false)
expect(hostUnderMemoryPressure({ availableMb: 40_000, totalMb: 64_158 }, c)).toBe(false)
})
it('a darwin-shaped reading (no swap, no PSI fields) can only ever use the watermark', () => {
// parseVmStat populates neither, so macOS cannot start firing on a signal never measured there.
const darwinish = { availableMb: 3000, totalMb: 24_576 }
expect(hostUnderMemoryPressure(darwinish, cfg({ minAvailableMb: 2458 }))).toBe(false)
expect(hostUnderMemoryPressure({ ...darwinish, availableMb: 100 }, cfg({ minAvailableMb: 2458 }))).toBe(true)
})
it('the new terms can be switched off, and off means off', () => {
expect(hostUnderMemoryPressure(swapSpent, cfg({ minAvailableMb: 6416, swapFreeRatio: 0 }))).toBe(false)
const psiOnly = { availableMb: 40_000, totalMb: 64_158, psiFullAvg60: 25 }
expect(hostUnderMemoryPressure(psiOnly, cfg({ minAvailableMb: 6416, psiFullAvg60: 0 }))).toBe(false)
})
it('drives planReap: the same sessions live or die on the swap reading alone', () => {
const sessions = [idle('nt-silent', 40)]
expect(planReap(sessions, healthyToday, NOW, cfg({ minAvailableMb: 6416 }))).toEqual([])
expect(planReap(sessions, swapSpent, NOW, cfg({ minAvailableMb: 6416 }))).toEqual(['nt-silent'])
})
})
describe('sessionBudgetConfig', () => {
const memOf = (totalMb: number) => ({ availableMb: Math.round(totalMb / 2), totalMb })
it('defaults: 10% of RAM watermark (floor 1GB), grace 6h, batch 8', () => {
const c = sessionBudgetConfig({}, memOf(64_000), 0)
expect(c).toEqual({
disabled: false,
minAvailableMb: 6400,
maxDetached: 33,
graceSec: 21_600,
batchMax: 8,
swapFreeRatio: 0.2,
swapAvailRatio: 0.25,
psiFullAvg60: 10
})
expect(sessionBudgetConfig({}, memOf(4000), 0).minAvailableMb).toBe(1024)
})
it('the detached cap SCALES WITH THE HOST instead of being the constant 48', () => {
// A share of host RAM over a nominal session cost, clamped to [8, 48]. The point is that a
// 16 GB laptop and a 62 GB server stop getting the same number: 48 detached agent sessions is
// ~23 GB of nominal RSS, i.e. more than a 16 GB machine physically has.
expect(sessionBudgetConfig({}, memOf(64_158), 0).maxDetached).toBe(33) // the production host
expect(sessionBudgetConfig({}, memOf(16_384), 0).maxDetached).toBe(8)
expect(sessionBudgetConfig({}, memOf(8192), 0).maxDetached).toBe(8) // floor holds a small host usable
// The ceiling is the historical constant, so this can only ever LOWER a cap, never raise one.
expect(sessionBudgetConfig({}, memOf(1_000_000), 0).maxDetached).toBe(48)
})
it('NO host reading (darwin) keeps the historical 48 rather than deriving from os.totalmem()', () => {
// Deriving here would silently change reaping on macOS — a cap of 12 on a 24 GB Mac — off a
// host figure whose meaning there this module has been burned by twice. The fallback total is
// still used for the watermark, which is the number that HAS a defined meaning.
const c = sessionBudgetConfig({}, null, 24_576)
expect(c.maxDetached).toBe(48)
expect(c.minAvailableMb).toBe(2458)
})
it('env overrides win; junk values fall back to the DERIVED cap, not to 48', () => {
const c = sessionBudgetConfig(
{
NODETERM_SESSION_MIN_AVAILABLE_MB: '3000',
NODETERM_SESSION_MAX_DETACHED: 'garbage',
NODETERM_SESSION_GRACE_HOURS: '12',
NODETERM_SESSION_REAP_DISABLED: '1'
},
memOf(64_000),
0
)
expect(c.minAvailableMb).toBe(3000)
expect(c.maxDetached).toBe(33)
expect(c.graceSec).toBe(43_200)
expect(c.disabled).toBe(true)
expect(sessionBudgetConfig({ NODETERM_SESSION_MAX_DETACHED: '5' }, memOf(64_000), 0).maxDetached).toBe(5)
})
it('the swap and PSI terms are tunable, and junk falls back', () => {
const c = (env: Record<string, string>) => sessionBudgetConfig(env, memOf(64_000), 0)
expect(c({ NODETERM_SESSION_SWAP_FREE_PCT: '35' }).swapFreeRatio) .toBeCloseTo(0.35)
expect(c({ NODETERM_SESSION_PSI_FULL_AVG60: '40' }).psiFullAvg60).toBe(40)
for (const v of ['abc', '', '0', '-3']) {
expect(c({ NODETERM_SESSION_SWAP_FREE_PCT: v }).swapFreeRatio).toBeCloseTo(0.2)
expect(c({ NODETERM_SESSION_PSI_FULL_AVG60: v }).psiFullAvg60).toBe(10)
}
})
})
// ---- service over fake exec ------------------------------------------------------------------
type Call = { args: string[] }
function fakeWorld(listings: Record<string, string[]>): {
calls: Call[]
exec: (bin: string, args: string[]) => Promise<string>
} {
const calls: Call[] = []
return {
calls,
exec: async (_bin, args) => {
calls.push({ args })
const socket = args[1]
if (args[2] === 'list-windows') {
const lines = listings[socket]
if (!lines) throw new Error('no server running')
return lines.join('\n')
}
return '' // kill-session
}
}
}
const OLD = String(NOW - 100 * 3600)
/**
* One `list-windows -a` row. `session_activity` is pinned FRESH (60 s) for the same reason the
* `idle` helper pins it: that is the only shape a live host ever presents, so the service tests
* exercise the honest clock rather than a stamp that would never be stale in production.
*/
const row = (name: string, clients: number, silentSince: number | string): string =>
`${name}|${clients}|${NOW - 60}|${silentSince}`
describe('createSessionReaper (service)', () => {
const base = {
readMem: () => ({ availableMb: 100, totalMb: 64_000 }),
env: {} as NodeJS.ProcessEnv,
nowSec: () => NOW,
log: () => {}
}
it('sweeps every socket, kills planned sessions on the right socket with exact-match targets', async () => {
const w = fakeWorld({
'node-terminal': [row('nt-local', 0, OLD)],
'nodeterm-rmt': [row('nt-remote', 0, OLD)]
})
const reaper = createSessionReaper({ ...base, tmuxBin: () => 'tmux', exec: w.exec })
expect(await reaper.sweep()).toBe(2)
const kills = w.calls.filter((c) => c.args[2] === 'kill-session')
expect(kills).toEqual([
{ args: ['-L', 'node-terminal', 'kill-session', '-t', '=nt-local'] },
{ args: ['-L', 'nodeterm-rmt', 'kill-session', '-t', '=nt-remote'] }
])
})
it('the kill log names BOTH clocks, with the silence leading', async () => {
// The attach clock's only production consumer is this log line. It rides along BECAUSE it
// disagrees with the silence: an operator cross-checking `tmux ls` sees `session_activity`
// minutes old and would read the reap as a bug unless the line itself explains the discrepancy.
// The numbers are pinned, not just the words — 100.0h of silence against a 0.0h-old attach is
// exactly the two-clock disagreement the whole change rests on.
const lines: string[] = []
const w = fakeWorld({ 'node-terminal': [row('nt-x', 0, OLD)] })
const reaper = createSessionReaper({ ...base, log: (m) => lines.push(m), tmuxBin: () => 'tmux', exec: w.exec })
expect(await reaper.sweep()).toBe(1)
expect(lines).toEqual([
'[session-budget] reaped detached session nt-x — no pane output for 100.0h; last attach 0.0h ago (socket node-terminal)'
])
})
it('re-verifies at kill time: a session attached between plan and kill is spared', async () => {
let first = true
const w = fakeWorld({})
const exec = async (bin: string, args: string[]): Promise<string> => {
if (args[2] === 'list-windows' && args[1] === 'node-terminal') {
if (first) {
first = false
return row('nt-x', 0, OLD)
}
return row('nt-x', 1, OLD) // now attached
}
return w.exec(bin, args)
}
const reaper = createSessionReaper({ ...base, tmuxBin: () => 'tmux', sockets: ['node-terminal'], exec })
expect(await reaper.sweep()).toBe(0)
expect(w.calls.filter((c) => c.args[2] === 'kill-session')).toHaveLength(0)
})
it('a socket whose listing fails contributes no candidates; the other socket still sweeps', async () => {
const w = fakeWorld({ 'nodeterm-rmt': [row('nt-r', 0, OLD)] }) // node-terminal listing throws
const reaper = createSessionReaper({ ...base, tmuxBin: () => 'tmux', exec: w.exec })
expect(await reaper.sweep()).toBe(1)
const kills = w.calls.filter((c) => c.args[2] === 'kill-session')
expect(kills).toEqual([{ args: ['-L', 'nodeterm-rmt', 'kill-session', '-t', '=nt-r'] }])
})
it('kill switch: disabled env runs no tmux commands at all', async () => {
const w = fakeWorld({ 'node-terminal': [row('nt-x', 0, OLD)] })
const reaper = createSessionReaper({
...base,
env: { NODETERM_SESSION_REAP_DISABLED: '1' },
tmuxBin: () => 'tmux',
exec: w.exec
})
expect(await reaper.sweep()).toBe(0)
expect(w.calls).toHaveLength(0)
})
it('tmux unavailable (bin=null) → quiet no-op', async () => {
const w = fakeWorld({ 'node-terminal': [row('nt-x', 0, OLD)] })
const reaper = createSessionReaper({ ...base, tmuxBin: () => null, exec: w.exec })
expect(await reaper.sweep()).toBe(0)
expect(w.calls).toHaveLength(0)
})
it('a failing kill is tolerated and does not abort the rest of the batch', async () => {
const w = fakeWorld({ 'node-terminal': [row('nt-a', 0, OLD), row('nt-b', 0, NOW - 99 * 3600)] })
const exec = async (bin: string, args: string[]): Promise<string> => {
if (args[2] === 'kill-session' && args[4] === '=nt-a') throw new Error('gone already')
return w.exec(bin, args)
}
const reaper = createSessionReaper({ ...base, tmuxBin: () => 'tmux', sockets: ['node-terminal'], exec })
expect(await reaper.sweep()).toBe(1) // nt-b still dies
})
it('healthy memory + under cap → lists but never kills', async () => {
const w = fakeWorld({ 'node-terminal': [row('nt-x', 0, OLD)] })
const reaper = createSessionReaper({
...base,
readMem: () => ({ availableMb: 30_000, totalMb: 64_000 }),
tmuxBin: () => 'tmux',
exec: w.exec
})
expect(await reaper.sweep()).toBe(0)
expect(w.calls.filter((c) => c.args[2] === 'kill-session')).toHaveLength(0)
})
it('…but the same host sweeps under an explicit external pressure reason', async () => {
const w = fakeWorld({ 'node-terminal': [row('nt-x', 0, OLD)] })
const reaper = createSessionReaper({
...base,
readMem: () => ({ availableMb: 30_000, totalMb: 64_000 }),
tmuxBin: () => 'tmux',
sockets: ['node-terminal'],
exec: w.exec
})
expect(await reaper.sweep({ pressure: 'pty' })).toBe(1)
})
it('an external reason never overrides the attached/grace exemptions', async () => {
const w = fakeWorld({
'node-terminal': [row('nt-watched', 1, OLD), row('nt-fresh', 0, NOW - 60)]
})
const reaper = createSessionReaper({
...base,
readMem: () => ({ availableMb: 30_000, totalMb: 64_000 }),
tmuxBin: () => 'tmux',
sockets: ['node-terminal'],
exec: w.exec
})
expect(await reaper.sweep({ pressure: 'pty' })).toBe(0)
expect(w.calls.filter((c) => c.args[2] === 'kill-session')).toHaveLength(0)
})
})
describe('planReap with no memory signal (the darwin shape)', () => {
const idle = (name: string, hoursAgo: number): SessionInfo => ({
name,
clients: 0,
activitySec: 1_000_000 - 60,
outputSec: 1_000_000 - hoursAgo * 3600
})
it('culls NOTHING on memory grounds when the reader reports null', () => {
// macOS: available BYTES is not the OS's pressure signal (measured: 82% used, 8.38 GB
// compressed, macOS's own graph GREEN). hostMemReader returns null there, and null must mean
// "no pressure signal", never "no memory". Absence of evidence may not cull a session.
const sessions = Array.from({ length: 20 }, (_, i) => idle(`nt-old-${i}`, 48))
const cfg = sessionBudgetConfig({}, null, 24576)
expect(planReap(sessions, null, 1_000_000, cfg)).toEqual([])
})
it('still culls past the detached-count cap without any memory signal', () => {
// The cap is not memory-based, so it survives — that is what keeps the reaper useful on macOS.
const sessions = Array.from({ length: 60 }, (_, i) => idle(`nt-old-${i}`, 48))
const cfg = sessionBudgetConfig({}, null, 24576)
expect(planReap(sessions, null, 1_000_000, cfg).length).toBeGreaterThan(0)
})
it('…and that cap is still the historical 48 there, not a figure derived from os.totalmem()', () => {
// 60 detached sessions against a cap of 48 is 12 over; a derived cap (24 GB → 12) would make it
// 48 over and reap a full batch on a Mac that has done nothing wrong.
expect(sessionBudgetConfig({}, null, 24576).maxDetached).toBe(48)
})
})
describe("the reaper's default memory reader", () => {
/**
* A SOURCE-level guard, deliberately, and here is why a behavioural one is not possible ON THIS
* PLATFORM: `hostMemReader` differs from `readMemInfo` ONLY on darwin, and CI runs on Linux,
* where the two are the same function. Reverting the default to `readMemInfo` therefore leaves
* every behavioural test green — measured, not assumed. The darwin-gated suite below IS the
* behavioural version of this guard; this string check is what stands in for it everywhere else.
*
* What it guards is the thing that actually broke: on macOS `readMemInfo` reports honest bytes,
* but available BYTES are not the OS's pressure signal (82% used with macOS's own graph GREEN,
* measured 2026-08-12), so a byte watermark culls sessions on a machine macOS says is fine.
*/
it('defaults to hostMemReader, not readMemInfo', () => {
const src = readFileSync(join(__dirname, 'session-budget.ts'), 'utf8')
expect(src).toContain('opts.readMem ?? hostMemReader()')
expect(src).not.toContain('opts.readMem ?? readMemInfo')
})
})
describe('darwin default reader: no byte reading may ever reap (behavioural)', () => {
/**
* Gated to darwin because only there do `hostMemReader` and `readMemInfo` diverge — on Linux
* they are the same function, so this test would FAIL there for the wrong reason (the real
* `/proc/meminfo` reading legitimately trips the impossible watermark below). On a Mac it is
* the real guard the source-text check above merely approximates.
*/
const onDarwin = it.skipIf(process.platform !== 'darwin')
onDarwin('readMemInfo yields an honest reading here — the discriminator is real, not vacuous', () => {
// If vm_stat parsing ever regressed to null on darwin, the reaping test below would pass for
// an empty reason (both readers null). This companion assertion is what keeps it meaningful.
const mem = readMemInfo()
expect(mem).not.toBeNull()
expect(mem!.totalMb).toBeGreaterThan(1024)
expect(mem!.availableMb).toBeGreaterThan(0)
expect(mem!.availableMb).toBeLessThan(mem!.totalMb)
})
onDarwin('without an injected readMem, sessions survive NO MATTER how full memory is', async () => {
// The watermark is set above any physically possible host (1 TB available), so ANY byte
// reading — however healthy the machine — counts as pressure. Only a reader that refuses to
// produce bytes at all (hostMemReader's darwin null) keeps these sessions alive. This encodes
// "memory fullness must never reap on macOS" without depending on the host's current load.
const w = fakeWorld({
'node-terminal': Array.from({ length: 20 }, (_, i) => row(`nt-idle-${i}`, 0, OLD))
})
const reaper = createSessionReaper({
tmuxBin: () => 'tmux',
sockets: ['node-terminal'],
exec: w.exec,
env: { NODETERM_SESSION_MIN_AVAILABLE_MB: '1000000000' },
nowSec: () => NOW,
log: () => {}
// deliberately NO readMem: the default reader is the thing under test
})
expect(await reaper.sweep()).toBe(0)
expect(w.calls.filter((c) => c.args[2] === 'kill-session')).toHaveLength(0)
})
})
describe('sessionBudgetConfig with fractional env values', () => {
// `null` mem, so the cap default is the historical 48 and these assertions keep testing the
// env-parsing trap they were written for rather than the new derivation.
const cfg = (env: Record<string, string>) => sessionBudgetConfig(env, null, 24576)
it('a fractional MAX_DETACHED falls back — it must never become a cap of ZERO', () => {
// Math.floor(0.5) === 0, and a cap of zero is not a smaller cap: every detached session counts
// as over-cap, so a full batch dies every sweep. The unsafe direction.
expect(cfg({ NODETERM_SESSION_MAX_DETACHED: '0.5' }).maxDetached).toBe(48)
expect(cfg({ NODETERM_SESSION_MAX_DETACHED: '0.9' }).maxDetached).toBe(48)
// A real value still works, and 1.5 still floors to 1 rather than falling back.
expect(cfg({ NODETERM_SESSION_MAX_DETACHED: '10' }).maxDetached).toBe(10)
expect(cfg({ NODETERM_SESSION_MAX_DETACHED: '1.5' }).maxDetached).toBe(1)
})
it('a fractional GRACE_HOURS means what it says — half an hour, not NO grace', () => {
// The plausible-input trap: `abc`/``/`0` all fell back safely, but `0.5` floored to zero grace,
// making a session reapable the moment it detached.
expect(cfg({ NODETERM_SESSION_GRACE_HOURS: '0.5' }).graceSec).toBe(1800)
expect(cfg({ NODETERM_SESSION_GRACE_HOURS: '0.25' }).graceSec).toBe(900)
expect(cfg({ NODETERM_SESSION_GRACE_HOURS: '2' }).graceSec).toBe(7200)
})
it('junk and zero still fall back to the safe defaults on every key', () => {
for (const v of ['abc', '', '0', '-3']) {
expect(cfg({ NODETERM_SESSION_GRACE_HOURS: v }).graceSec).toBe(6 * 3600)
expect(cfg({ NODETERM_SESSION_MAX_DETACHED: v }).maxDetached).toBe(48)
expect(cfg({ NODETERM_SESSION_REAP_BATCH: v }).batchMax).toBe(8)
}
})
})
describe('createSessionReaper — session-host leg (no tmux, Windows)', () => {
const base = {
readMem: () => ({ availableMb: 100, totalMb: 64_000 }), // under the watermark: pressure
env: {} as NodeJS.ProcessEnv,
nowSec: () => NOW,
log: () => {}
}
const hostRow = (name: string, clients: number, idleH: number): SessionInfo => ({
name,
clients,
activitySec: NOW - idleH * 3600,
outputSec: NOW - idleH * 3600
})
const fakeHost = (listings: Array<SessionInfo[] | null>) => {
const killed: string[] = []
let call = 0
return {
killed,
backend: {
list: async () => listings[Math.min(call++, listings.length - 1)],
kill: async (name: string) => {
killed.push(name)
return true
}
}
}
}
it('reaps detached, silent sessions past the grace window and spares attached ones', async () => {
const rows = [hostRow('nt-idle', 0, 100), hostRow('nt-watched', 1, 100), hostRow('nt-fresh', 0, 1)]
const h = fakeHost([rows])
const lines: string[] = []
const reaper = createSessionReaper({
...base,
log: (m) => lines.push(m),
tmuxBin: () => null,
sessionHost: () => h.backend
})
expect(await reaper.sweep()).toBe(1)
expect(h.killed).toEqual(['nt-idle'])
expect(lines).toEqual([
'[session-budget] reaped detached session nt-idle — no pane output for 100.0h (session host)'
])
})
it('a failed (null) listing kills nothing', async () => {
const h = fakeHost([null])
const reaper = createSessionReaper({ ...base, tmuxBin: () => null, sessionHost: () => h.backend })
expect(await reaper.sweep()).toBe(0)
expect(h.killed).toEqual([])
})
it('a listing that throws kills nothing and the sweep does not throw', async () => {
const reaper = createSessionReaper({
...base,
tmuxBin: () => null,
sessionHost: () => ({
list: async () => {
throw new Error('host gone')
},
kill: async () => true
})
})
expect(await reaper.sweep()).toBe(0)
})
it('re-verifies at kill time: attached, freshly active, vanished or unlistable sessions are spared', async () => {
const planned = [hostRow('nt-a', 0, 100), hostRow('nt-b', 0, 100), hostRow('nt-c', 0, 100)]
const fresh = [hostRow('nt-a', 1, 100), hostRow('nt-b', 0, 0)] // nt-c vanished
const h = fakeHost([planned, fresh])
const reaper = createSessionReaper({ ...base, tmuxBin: () => null, sessionHost: () => h.backend })
expect(await reaper.sweep()).toBe(0)
expect(h.killed).toEqual([])
const unlistable = fakeHost([planned, null])
const r2 = createSessionReaper({ ...base, tmuxBin: () => null, sessionHost: () => unlistable.backend })
expect(await r2.sweep()).toBe(0)
expect(unlistable.killed).toEqual([])
})
it('a kill the backend did not confirm is not counted', async () => {
const reaper = createSessionReaper({
...base,
tmuxBin: () => null,
sessionHost: () => ({ list: async () => [hostRow('nt-a', 0, 100)], kill: async () => false })
})
expect(await reaper.sweep()).toBe(0)
})
it('without pressure and under the cap, nothing is planned (same budget rules as tmux)', async () => {
const h = fakeHost([[hostRow('nt-idle', 0, 100)]])
const reaper = createSessionReaper({
...base,
readMem: () => ({ availableMb: 60_000, totalMb: 64_000 }),
tmuxBin: () => null,
sessionHost: () => h.backend
})
expect(await reaper.sweep()).toBe(0)
expect(await reaper.sweep({ pressure: 'pty' })).toBe(1)
})
it('is never consulted while tmux exists, and the kill switch covers it too', async () => {
let asked = 0
const backend = () => {
asked++
return fakeHost([[hostRow('nt-idle', 0, 100)]]).backend
}
const w = fakeWorld({})
const reaper = createSessionReaper({ ...base, tmuxBin: () => 'tmux', exec: w.exec, sessionHost: backend })
await reaper.sweep()
expect(asked).toBe(0)
const off = createSessionReaper({
...base,
env: { NODETERM_SESSION_REAP_DISABLED: '1' },
tmuxBin: () => null,
sessionHost: backend
})
expect(await off.sweep()).toBe(0)
expect(asked).toBe(0)
})
it('no backend (session host not in use) is the historical no-op', async () => {
const reaper = createSessionReaper({ ...base, tmuxBin: () => null, sessionHost: () => undefined })
expect(await reaper.sweep()).toBe(0)
})
})