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.

35.8 KB
Raw Blame
import { describe, it, expect, vi } from 'vitest'
import fs from 'fs'
import {
  indexProcesses,
  rollupTree,
  parseProcessTable,
  parsePaneList,
  buildReport,
  collectSessionHostMemory,
  collectSessionMemory,
  defaultProcessTableReader,
  isNoServerError,
  processLabel,
  type ProcEntry,
  type SessionMemoryReport
} from './session-memory'
import type { SessionHostListing } from './session-host-client'

const P = (pid: number, ppid: number, rssKb: number): ProcEntry => ({ pid, ppid, rssKb })

describe('indexProcesses + rollupTree', () => {
  it('sums a pane pid and every descendant, splitting self from children', () => {
    // pane(100) -> claude(200) -> mcp(300), and claude also has mcp2(301)
    const { table, kids } = indexProcesses([
      P(100, 1, 1024),
      P(200, 100, 350 * 1024),
      P(300, 200, 30 * 1024),
      P(301, 200, 20 * 1024)
    ])
    const r = rollupTree(table, kids, 100)
    expect(r.selfMb).toBe(1)
    expect(r.childrenMb).toBe(400)
    expect(r.childCount).toBe(3)
    expect(r.totalMb).toBe(401)
  })

  it('returns zeros for a pid that is not in the table', () => {
    const { table, kids } = indexProcesses([P(100, 1, 1024)])
    expect(rollupTree(table, kids, 999)).toEqual({
      selfMb: 0,
      childrenMb: 0,
      childCount: 0,
      totalMb: 0,
      largestMb: 0
    })
  })

  it('names the largest process wherever it sits in the tree, without taking it out of the total', () => {
    // The row's number is the whole tree, and the shell at its root is a few MB. What a reader
    // needs next is which process holds it: here a grandchild, not the pane's direct child.
    const { table, kids } = indexProcesses([
      { ...P(100, 1, 4 * 1024), name: '-zsh' },
      { ...P(200, 100, 500 * 1024), name: 'claude' },
      { ...P(300, 200, 900 * 1024), name: 'dart' }
    ])
    const r = rollupTree(table, kids, 100)
    expect(r.largestName).toBe('dart')
    expect(r.largestMb).toBe(900)
    expect(r.totalMb).toBe(1404)
  })

  it('can name the pane root itself: a pane started directly on the agent has no bigger child', () => {
    const { table, kids } = indexProcesses([
      { ...P(100, 1, 300 * 1024), name: 'claude' },
      { ...P(200, 100, 20 * 1024), name: 'node' }
    ])
    expect(rollupTree(table, kids, 100)).toMatchObject({ largestName: 'claude', largestMb: 300 })
  })

  it('reports the largest size with no name when the reader has none', () => {
    const { table, kids } = indexProcesses([P(100, 1, 1024), P(200, 100, 2048)])
    const r = rollupTree(table, kids, 100)
    expect(r.largestMb).toBe(2)
    expect(r.largestName).toBeUndefined()
  })

  it('does not loop forever on a cyclic ppid chain', () => {
    // A pid whose parent chain points back at it must not hang the sweep.
    const { table, kids } = indexProcesses([P(100, 200, 1024), P(200, 100, 1024)])
    const r = rollupTree(table, kids, 100)
    expect(r.totalMb).toBe(2)
    expect(r.childCount).toBe(1)
  })
})

describe('processLabel', () => {
  it('reads an absolute path by its file name, spaces included', () => {
    expect(processLabel('/bin/zsh')).toBe('zsh')
    expect(processLabel('/Applications/Wow Keywords.app/Contents/MacOS/Wow Keywords')).toBe('Wow Keywords')
  })

  it('leaves a process title alone even when it holds a slash', () => {
    // macOS `ps` prints a retitled process verbatim. A basename here would print `mcp@latest`.
    expect(processLabel('npm exec @playwright/mcp@latest')).toBe('npm exec @playwright/mcp@latest')
  })

  it('drops the leading dash of a login shell', () => {
    expect(processLabel('-zsh')).toBe('zsh')
  })

  it('strips control and format characters: a process title is whatever the process set', () => {
    expect(processLabel('cla\u0007ude\u202e')).toBe('claude')
  })

  it('caps a long title', () => {
    const label = processLabel('x'.repeat(200)) as string
    expect(Array.from(label)).toHaveLength(40)
    expect(label.endsWith('…')).toBe(true)
  })

  it('answers nothing when there is nothing left to show', () => {
    expect(processLabel(undefined)).toBeUndefined()
    expect(processLabel('')).toBeUndefined()
    expect(processLabel('\u0007')).toBeUndefined()
  })
})

describe('parseProcessTable', () => {
  it('keeps the name column, spaces included', () => {
    const out = parseProcessTable(
      '  PID  PPID    RSS COMM\n  100     1   1024 /Applications/Wow Keywords.app/Contents/MacOS/Wow Keywords\n  200   100   2048 claude\n'
    )
    expect(out.map((e) => e.name)).toEqual([
      '/Applications/Wow Keywords.app/Contents/MacOS/Wow Keywords',
      'claude'
    ])
  })

  it('still reads a three-column table, with no name', () => {
    expect(parseProcessTable('100 1 1024\n')[0].name).toBeUndefined()
  })

  it('parses ps output and skips the header and malformed lines', () => {
    const out = parseProcessTable(
      '  PID  PPID    RSS COMMAND\n' +
        '  100     1   1024 tmux\n' +
        'garbage line\n' +
        '  200   100 358400 claude\n'
    )
    expect(out).toEqual([
      { pid: 100, ppid: 1, rssKb: 1024, name: 'tmux' },
      { pid: 200, ppid: 100, rssKb: 358400, name: 'claude' }
    ])
  })

  it('returns an empty array for empty input rather than throwing', () => {
    expect(parseProcessTable('')).toEqual([])
  })
})

describe('parsePaneList', () => {
  it('parses the pipe-delimited pane list and skips malformed lines', () => {
    // `nt-zero||sh` is the phantom case: an empty pid field parses as 0, which IS finite, so a
    // finite-only guard would emit a 0 MB row for a pid that cannot exist.
    expect(
      parsePaneList('nt-term-a|100|claude\nbroken\nnt-term-b|200|zsh\n|300|x\nnt-zero||sh\n')
    ).toEqual([
      { session: 'nt-term-a', panePid: 100, command: 'claude' },
      { session: 'nt-term-b', panePid: 200, command: 'zsh' }
    ])
  })
})

describe('buildReport', () => {
  it('rolls up each nt- session and sorts by total descending', () => {
    const r = buildReport(
      [
        { session: 'nt-small', panePid: 100, command: 'zsh' },
        { session: 'nt-big', panePid: 200, command: 'claude' }
      ],
      [
        P(100, 1, 40 * 1024),
        P(200, 1, 350 * 1024),
        P(201, 200, 50 * 1024)
      ],
      { availableMb: 1000, totalMb: 64000 }
    )
    expect(r.ok).toBe(true)
    expect(r.rows.map((x) => x.session)).toEqual(['nt-big', 'nt-small'])
    expect(r.rows[0]).toMatchObject({
      nodeId: 'big',
      totalMb: 400,
      selfMb: 350,
      childrenMb: 50,
      childCount: 1,
      command: 'claude'
    })
  })

  it('ignores sessions that are not nt- prefixed', () => {
    const r = buildReport(
      [{ session: 'my-own-tmux', panePid: 100, command: 'zsh' }],
      [P(100, 1, 40 * 1024)],
      null
    )
    expect(r.rows).toEqual([])
  })
})

describe('collectSessionMemory', () => {
  const table = [P(100, 1, 40 * 1024), P(200, 1, 350 * 1024)]

  it('reports ok:false with no rows when the process table cannot be read', async () => {
    const r = await collectSessionMemory({
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1'],
      exec: async () => 'nt-a|100|claude\n',
      readTable: () => null,
      readMem: () => ({ availableMb: 1, totalMb: 2 })
    })
    // "could not look" must never render as "uses nothing".
    expect(r.ok).toBe(false)
    expect(r.rows).toEqual([])
    // The host total is still a real reading — the failure path must not throw it away.
    expect(r.mem).toEqual({ availableMb: 1, totalMb: 2 })
  })

  it('reports ok:true with no rows when tmux has no server (a real answer)', async () => {
    const r = await collectSessionMemory({
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1'],
      exec: async () => {
        throw new Error('no server running')
      },
      readTable: () => table,
      readMem: () => null
    })
    expect(r.ok).toBe(true)
    expect(r.rows).toEqual([])
  })

  it('reports ok:false when tmux is unavailable entirely', async () => {
    const r = await collectSessionMemory({ tmuxBin: () => null, readTable: () => table })
    expect(r.ok).toBe(false)
    expect(r.rows).toEqual([])
  })

  it('counts "no server" as an answer but a permission failure as a failure', () => {
    expect(isNoServerError('no server running on /tmp/tmux-0/node-terminal')).toBe(true)
    expect(isNoServerError('error connecting to /tmp/x (No such file or directory)')).toBe(true)
    // A socket dir we may not read says nothing about whether sessions exist there.
    expect(isNoServerError('error connecting to /tmp/x (Permission denied)')).toBe(false)
    expect(isNoServerError('killed: timeout')).toBe(false)
    // The regression the anchor exists for: stderr that merely CONTAINS the errno phrase. A tmux
    // client that cannot load a library fails this way on EVERY socket — same binary — so counting
    // it as an answer would print "no sessions" while the already-running server holds live ones.
    expect(
      isNoServerError(
        'Command failed: tmux -L node-terminal list-panes\ntmux: error while loading shared ' +
          'libraries: libtinfo.so.6: cannot open shared object file: No such file or directory'
      )
    ).toBe(false)
    // Same shape one layer out: a dead ssh ControlMaster, which this sweep may later run over.
    expect(isNoServerError('Control socket connect(/tmp/cm.sock): No such file or directory')).toBe(
      false
    )
  })

  it('reports ok:false when NO socket answered', async () => {
    // One socket erroring is normal (nobody used it). Every socket erroring means we never looked,
    // and "we never looked" must not render as "there are no sessions".
    const r = await collectSessionMemory({
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1', 's2'],
      exec: async () => {
        throw new Error('connect failed')
      },
      readTable: () => table,
      readMem: () => null
    })
    expect(r.ok).toBe(false)
    expect(r.rows).toEqual([])
  })

  it('merges panes from every socket and the first socket wins a duplicate session', async () => {
    const r = await collectSessionMemory({
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1', 's2'],
      exec: async (_bin, args) =>
        args[1] === 's1' ? 'nt-a|100|zsh\n' : 'nt-b|200|claude\nnt-a|999|claude\n',
      readTable: () => table,
      readMem: () => null
    })
    expect(r.rows.map((x) => x.session).sort()).toEqual(['nt-a', 'nt-b'])
    // s2 also reported nt-a, with a different pid and command: s1's entry must be the one kept.
    expect(r.rows.find((x) => x.session === 'nt-a')).toMatchObject({
      panePid: 100,
      command: 'zsh'
    })
  })

  it('routes the ps fallback through the injected exec seam', async () => {
    // With no readTable injected the default /proc reader runs first; make it fail so the `ps`
    // fallback is reached on every platform, including the Linux box this suite runs on.
    const spy = vi.spyOn(fs, 'readdirSync').mockImplementation(() => {
      throw new Error('/proc unreadable')
    })
    try {
      const calls: string[] = []
      const r = await collectSessionMemory({
        tmuxBin: () => '/usr/bin/tmux',
        sockets: ['s1'],
        exec: async (bin) => {
          calls.push(bin)
          if (bin === 'ps') return '  PID  PPID    RSS\n  100     1   1024\n'
          return 'nt-a|100|zsh\n'
        },
        readMem: () => null
      })
      // The `ps` call must come THROUGH the seam, not around it — otherwise this path can never
      // be driven by a test and the file's "every exec is injectable" promise is false.
      expect(calls).toContain('ps')
      expect(r.ok).toBe(true)
      expect(r.rows[0]).toMatchObject({ session: 'nt-a', selfMb: 1 })
    } finally {
      spy.mockRestore()
    }
  })
})

import { parseVmStat, darwinMemInfo, parseTopFootprint } from './session-memory'

/** Shaped from Apple's documented `vm_stat` format, at a 16 KiB page (Apple Silicon). COMPOSED, not
 *  captured — nobody in this loop has a Mac. Numbers chosen so the arithmetic is checkable by hand:
 *  anonymous 800k - purgeable 50k + wired 150k + compressor 100k = 1,000,000 pages.
 *  1,000,000 x 16384 B = 15625 MiB used of a 24576 MiB machine, i.e. 8951 MiB available. */
const VM_STAT = [
  'Mach Virtual Memory Statistics: (page size of 16384 bytes)',
  'Pages free:                                50000.',
  'Pages active:                             600000.',
  'Pages inactive:                           400000.',
  'Pages speculative:                         30000.',
  'Pages throttled:                               0.',
  'Pages wired down:                         150000.',
  'Pages purgeable:                           50000.',
  '"Translation faults":                  987654321.',
  'Pages occupied by compressor:             100000.',
  'File-backed pages:                        700000.',
  'Anonymous pages:                          800000.'
].join('\n')

const TOTAL_BYTES = 24576 * 1048576

describe('parseVmStat', () => {
  it('reports app+wired+compressed as used, not the near-zero free page count', () => {
    // The bug this exists for: `Pages free` is 50000 (≈781 MiB) on a machine with 8.4 GiB genuinely
    // available, because macOS holds the rest as reclaimable cache.
    expect(parseVmStat(VM_STAT, TOTAL_BYTES)).toEqual({ availableMb: 8951, totalMb: 24576 })
  })

  it('reads the page size from the header rather than assuming 4096', () => {
    // Same class as the Linux statm bug: a hard-coded 4096 would report a QUARTER of the real usage
    // on Apple Silicon, i.e. an alarmingly empty machine.
    const fourK = parseVmStat(VM_STAT.replace('16384 bytes', '4096 bytes'), TOTAL_BYTES)
    // 1,000,000 x 4096 B = 3906 MiB, so the machine would read 5044 MiB emptier than it is.
    expect(fourK).toEqual({ availableMb: 20670, totalMb: 24576 })
  })

  it('subtracts purgeable pages from anonymous — they are droppable cache, not app memory', () => {
    const noPurge = parseVmStat(VM_STAT.replace(/Pages purgeable:.*\n/, ''), TOTAL_BYTES)
    // Without the subtraction the machine reads 50000 pages (781 MiB) fuller than it is.
    expect(noPurge?.availableMb).toBe(8951 - 781)
  })

  it('returns null when a field it needs is missing, rather than a partial number', () => {
    expect(parseVmStat(VM_STAT.replace(/Pages wired down:.*\n/, ''), TOTAL_BYTES)).toBeNull()
    expect(parseVmStat('not vm_stat output', TOTAL_BYTES)).toBeNull()
    expect(parseVmStat(VM_STAT, 0)).toBeNull()
  })

  it('never reports negative availability on a heavily compressed machine', () => {
    const tiny = parseVmStat(VM_STAT, 1024 * 1048576)
    expect(tiny?.availableMb).toBe(0)
  })
})

describe('darwinMemInfo', () => {
  it('reports null when vm_stat cannot run — never the os.freemem() value', () => {
    // The whole point. Falling back to os.freemem() here would restore the bug: on macOS it reads
    // near zero, the reaper's 10%-of-RAM watermark reads as permanent pressure, and idle detached
    // sessions get reaped every sweep. A confirmed field symptom ("my sessions keep disappearing").
    // planReap treats null as NO pressure, so no signal is the safe answer.
    expect(
      darwinMemInfo(() => {
        throw new Error('spawn vm_stat ENOENT')
      }, TOTAL_BYTES)
    ).toBeNull()
  })

  it('reports null on output it cannot parse', () => {
    expect(darwinMemInfo(() => 'garbage', TOTAL_BYTES)).toBeNull()
  })

  it('passes a good reading through', () => {
    expect(darwinMemInfo(() => VM_STAT, TOTAL_BYTES)).toEqual({ availableMb: 8951, totalMb: 24576 })
  })
})

/** CAPTURED from a real Mac (2026-08-12), not composed: the exact header block, the blank line, the
 *  `PID    MEM` header and real rows. The bracketed spacing quirks the capture surfaced are kept —
 *  the MEM column is LEFT-aligned in five chars, so short values carry trailing spaces. */
const TOP_REAL = [
  'Processes: 973 total, 5 running, 968 sleeping, 5566 threads',
  '2026/08/12 04:40:17',
  'Load Avg: 4.13, 4.82, 6.19',
  'CPU usage: 22.1% user, 19.11% sys, 58.86% idle',
  'SharedLibs: 501M resident, 114M data, 85M linkedit.',
  'MemRegions: 887125 total, 6692M resident, 248M private, 2163M shared.',
  'PhysMem: 23G used (2941M wired, 8908M compressor), 83M unused.',
  'VM: 460T vsize, 6144M framework vsize, 210882(0) swapins, 517764(0) swapouts.',
  'Networks: packets: 754492311/1003G in, 62312609/20G out.',
  'Disks: 43587984/769G read, 23106973/357G written.',
  '',
  'PID    MEM  ',
  '99554  3696K',
  '99132  6288K',
  '98779  12M  ',
  '97530  8433K',
  '97519  29M  ',
  '70698  1314M',
  '0      36M  '
].join('\n')

describe('parseTopFootprint', () => {
  it('parses the real capture, including the left-aligned trailing spaces', () => {
    const m = parseTopFootprint(TOP_REAL)
    expect(m.get(99554)).toBe(3696)
    expect(m.get(8433)).toBeUndefined()
    expect(m.get(97530)).toBe(8433)
    // `12M  ` carries two trailing spaces — the quirk that makes a /M$/ regex miss two thirds of
    // the column on a real host.
    expect(m.get(98779)).toBe(12 * 1024)
    expect(m.get(70698)).toBe(1314 * 1024)
  })

  it('reads pid 0 (kernel_task), which is present and accessible', () => {
    expect(parseTopFootprint(TOP_REAL).get(0)).toBe(36 * 1024)
  })

  it('ignores the header block — those lines contain digits and units too', () => {
    // `PhysMem: 23G used (2941M wired, ...)` would be a tempting false match.
    const m = parseTopFootprint(TOP_REAL)
    expect(m.size).toBe(7)
  })

  it('accepts G even though it was never observed on the capture host', () => {
    // A 1314M process stayed in M, so the G threshold is unknown — but top's own header prints
    // `PhysMem: 23G`, so the unit exists and the parser must not choke on it.
    expect(parseTopFootprint('PID    MEM\n42     3G   ').get(42)).toBe(3 * 1024 * 1024)
  })

  it('SKIPS a row whose unit it does not recognise rather than guessing a scale', () => {
    // `B` and any restricted-process rendering were not observed on the capture host and are
    // deliberately not invented. A wrong scale is a wrong number presented as a fact.
    const m = parseTopFootprint('PID    MEM\n42     500Q \n43     7K')
    expect(m.has(42)).toBe(false)
    expect(m.get(43)).toBe(7)
  })

  it('returns an empty map when there is no PID/MEM header at all', () => {
    expect(parseTopFootprint('not top output').size).toBe(0)
  })
})

describe('collectSessionMemory on darwin', () => {
  const asDarwin = (fn: () => Promise<void>) => async (): Promise<void> => {
    const real = Object.getOwnPropertyDescriptor(process, 'platform')!
    Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true })
    try {
      await fn()
    } finally {
      Object.defineProperty(process, 'platform', real)
    }
  }

  const run = async (): Promise<{ calls: string[]; rows: unknown }> => {
    const calls: string[] = []
    const r = await collectSessionMemory({
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1'],
      exec: async (bin, args) => {
        calls.push(bin)
        if (bin.includes('tmux')) return 'nt-a|4242|claude\n'
        if (bin === 'ps') return 'PID PPID RSS\n4242 1 100000\n'
        // 4242's footprint is DOUBLE its rss — the measured idle-process shape.
        return 'PID    MEM  \n4242   200000K'
      },
      readTable: undefined,
      readMem: () => null
    })
    return { calls, rows: r.rows }
  }

  it(
    'prefers phys_footprint over rss — the idle-session number rss halves',
    asDarwin(async () => {
      const { calls, rows } = await run()
      expect(calls).toContain('top')
      // 200000 kB, not the 100000 kB `ps` reported.
      expect((rows as { selfMb: number }[])[0].selfMb).toBe(Math.round(200000 / 1024))
    })
  )

  it(
    'asks ps for the process name, and says the rows are physical footprint',
    asDarwin(async () => {
      let psArgs: string[] = []
      const r = await collectSessionMemory({
        tmuxBin: () => '/usr/bin/tmux',
        sockets: ['s1'],
        exec: async (bin, args) => {
          if (bin.includes('tmux')) return 'nt-a|4242|claude\n'
          if (bin === 'ps') {
            psArgs = args
            return 'PID PPID RSS COMM\n4242 1 100000 -zsh\n'
          }
          return 'PID    MEM  \n4242   200000K'
        },
        readTable: undefined,
        readMem: () => null
      })
      expect(psArgs).toEqual(['-eo', 'pid,ppid,rss,comm'])
      expect(r.metric).toBe('footprint')
      expect(r.rows[0].largestName).toBe('zsh')
    })
  )

  it(
    'the "nodeterm itself" group reuses that SAME top read — footprint for a covered pid, nothing for a missed one',
    asDarwin(async () => {
      const calls: string[] = []
      const r = await collectSessionMemory({
        tmuxBin: () => '/usr/bin/tmux',
        sockets: ['s1'],
        exec: async (bin) => {
          calls.push(bin)
          if (bin.includes('tmux')) return 'nt-a|4242|claude\n'
          // 900 = the GPU helper: rss 120 MB. 901 = a renderer top did not list.
          if (bin === 'ps') return 'PID PPID RSS\n4242 1 100000\n900 1 122880\n901 1 307200\n'
          return 'PID    MEM  \n4242   200000K\n900    1600M\n'
        },
        readTable: undefined,
        readMem: () => null,
        appProcesses: () => [
          { pid: 900, type: 'GPU' },
          { pid: 901, type: 'Tab' }
        ]
      })
      // ONE top for the whole panel, sessions and app together (~0.5 s each, measured).
      expect(calls.filter((c) => c === 'top')).toHaveLength(1)
      expect(r.app?.groups).toEqual([
        { kind: 'gpu', count: 1, mb: 1600 },
        { kind: 'renderer', count: 1 }
      ])
    })
  )
})

import { parseMemInfoText, parsePsiMemory, readMemInfo } from './session-memory'

/** A verbatim excerpt of the production host's /proc/meminfo, 2026-08-15 (62.7 GB, swap 74% spent). */
const MEMINFO = `MemTotal:       65697400 kB
MemFree:         4154020 kB
MemAvailable:   13804628 kB
Buffers:          412300 kB
Cached:          9216440 kB
SwapCached:       501232 kB
SwapTotal:       8388604 kB
SwapFree:        2192260 kB
Dirty:               736 kB
`

const PSI = `some avg10=0.00 avg60=1.25 avg300=0.18 total=29288181130
full avg10=0.00 avg60=0.75 avg300=0.15 total=25621111809
`

describe('parseMemInfoText', () => {
  it('reads the required pair and the optional swap pair from ONE snapshot', () => {
    expect(parseMemInfoText(MEMINFO)).toEqual({
      availableMb: 13481,
      totalMb: 64158,
      swapTotalMb: 8192,
      swapFreeMb: 2141,
      // The pill's copy of the same instant, in the display-only object the reaper never reads.
      display: { swapUsedMb: 8192 - 2141, swapTotalMb: 8192 }
    })
  })

  it('MemAvailable/MemTotal are required — a /proc we do not understand yields NO reading', () => {
    // Not a partial object: a reading missing its primary field would be a number the watermark
    // could still compare against, which is the "wrong number presented as a fact" failure.
    expect(parseMemInfoText(MEMINFO.replace(/MemAvailable:.*\n/, ''))).toBeNull()
    expect(parseMemInfoText(MEMINFO.replace(/MemTotal:.*\n/, ''))).toBeNull()
    expect(parseMemInfoText('garbage')).toBeNull()
  })

  it('swap is OMITTED, not zeroed, when the kernel does not report it', () => {
    // The distinction the swap term depends on: `undefined` means "did not measure" and disables
    // the term, whereas `0` would read as "swap totally exhausted" and could only ever reap MORE.
    const noSwap = parseMemInfoText(MEMINFO.replace(/SwapTotal:.*\n/, '').replace(/SwapFree:.*\n/, ''))
    expect(noSwap).toEqual({ availableMb: 13481, totalMb: 64158 })
    expect(noSwap).not.toHaveProperty('swapTotalMb')
    expect(noSwap).not.toHaveProperty('swapFreeMb')
  })

  it('half a swap reading is no swap reading (a free without a total cannot be a ratio)', () => {
    const half = parseMemInfoText(MEMINFO.replace(/SwapTotal:.*\n/, ''))
    expect(half).not.toHaveProperty('swapFreeMb')
  })

  it('a swapless host reports a real zero TOTAL, which every consumer guard turns off', () => {
    const off = parseMemInfoText(MEMINFO.replace(/SwapTotal:.*/, 'SwapTotal:             0 kB').replace(/SwapFree:.*/, 'SwapFree:              0 kB'))
    expect(off).toMatchObject({ swapTotalMb: 0, swapFreeMb: 0 })
  })
})

describe('parsePsiMemory', () => {
  it('reads avg60 from both lines', () => {
    expect(parsePsiMemory(PSI)).toEqual({ psiSomeAvg60: 1.25, psiFullAvg60: 0.75 })
  })

  it('takes avg60 specifically — not avg10 and not avg300', () => {
    // The cadence argument: the reaper sweeps every 10 minutes, so avg10 is noise and avg300 stays
    // elevated through a recovery. Distinct values in every column make a mix-up visible.
    const distinct = 'some avg10=11.00 avg60=22.00 avg300=33.00 total=1\nfull avg10=44.00 avg60=55.00 avg300=66.00 total=2\n'
    expect(parsePsiMemory(distinct)).toEqual({ psiSomeAvg60: 22, psiFullAvg60: 55 })
  })

  it('does not confuse the some line for the full line', () => {
    expect(parsePsiMemory('some avg10=0.00 avg60=9.00 avg300=0.00 total=1\n')).toEqual({ psiSomeAvg60: 9 })
  })

  it('an unreadable or absent PSI file yields NO figures, never zeros', () => {
    expect(parsePsiMemory('')).toEqual({})
    expect(parsePsiMemory('garbage')).toEqual({})
    expect(parsePsiMemory('some avg10=0.00 avg300=0.18 total=1\n')).toEqual({})
  })
})

describe('readMemInfo on this Linux host (integration)', () => {
  const onLinux = it.skipIf(process.platform !== 'linux')

  onLinux('carries swap alongside the available/total pair', () => {
    const m = readMemInfo()
    expect(m).not.toBeNull()
    expect(m!.totalMb).toBeGreaterThan(0)
    // Swap is not guaranteed configured, but if the kernel reports a total it must report a free.
    if (m!.swapTotalMb !== undefined) {
      expect(m!.swapFreeMb).toBeDefined()
      expect(m!.swapFreeMb!).toBeLessThanOrEqual(m!.swapTotalMb!)
    }
  })

  onLinux('PSI is optional and never breaks the reading', () => {
    const m = readMemInfo()
    expect(m).not.toBeNull()
    if (m!.psiFullAvg60 !== undefined) expect(m!.psiFullAvg60).toBeGreaterThanOrEqual(0)
  })
})

import {
  appProcessKind,
  appSelfMemory,
  parsePressureLevel,
  parseSwapUsage,
  type AppProcessSample
} from './session-memory'

/** Captured live on a Mac, 2026-10-19 (`sysctl vm.swapusage`). */
const SWAPUSAGE = 'vm.swapusage: total = 9216.00M  used = 7853.62M  free = 1362.38M  (encrypted)\n'

describe('parseSwapUsage (darwin)', () => {
  it('reads used and total from the live string, prefixed or not', () => {
    expect(parseSwapUsage(SWAPUSAGE)).toEqual({ swapUsedMb: 7854, swapTotalMb: 9216 })
    expect(parseSwapUsage(SWAPUSAGE.replace('vm.swapusage: ', ''))).toEqual({ swapUsedMb: 7854, swapTotalMb: 9216 })
  })

  it('accepts K and G, and passes a real zero through', () => {
    expect(parseSwapUsage('total = 2.00G  used = 512.00K  free = 1.99G')).toEqual({ swapUsedMb: 1, swapTotalMb: 2048 })
    expect(parseSwapUsage('total = 0.00M  used = 0.00M  free = 0.00M')).toEqual({ swapUsedMb: 0, swapTotalMb: 0 })
  })

  it('an unknown unit or a missing half yields NOTHING, never a guessed scale or a zero', () => {
    expect(parseSwapUsage('total = 9216.00T  used = 1.00M  free = 1.00M')).toEqual({})
    expect(parseSwapUsage('total = 9216.00M  free = 1.00M')).toEqual({})
    expect(parseSwapUsage('')).toEqual({})
  })
})

describe('parsePressureLevel (darwin)', () => {
  it('maps xnu levels 1/2/4 and nothing else', () => {
    expect(parsePressureLevel('1')).toBe('normal')
    expect(parsePressureLevel('kern.memorystatus_vm_pressure_level: 2\n')).toBe('warn')
    expect(parsePressureLevel('4')).toBe('critical')
    for (const junk of ['0', '3', '12', '', 'unknown oid', 'kern.memorystatus_vm_pressure_level: 21'])
      expect(parsePressureLevel(junk)).toBeUndefined()
  })
})

describe('darwinMemInfo display extras', () => {
  /** One `sysctl <names…>` run: the known oids print their `name: value` lines, in order; an
   *  unknown one makes the run exit non-zero, which the caller hands over as the partial stdout
   *  (`readMemInfo`'s runner) — so here a run with no known oid at all throws. */
  const sysctl = (answers: Record<string, string>) => (names: string[]): string => {
    const lines = names.filter((n) => answers[n] !== undefined).map((n) => answers[n])
    if (lines.length === 0) throw new Error(`unknown oid ${names.join(' ')}`)
    return lines.join('\n') + '\n'
  }

  it('reads swap and pressure in ONE sysctl run, never one per field', () => {
    const runs: string[][] = []
    const both = sysctl({
      'vm.swapusage': SWAPUSAGE.trimEnd(),
      'kern.memorystatus_vm_pressure_level': 'kern.memorystatus_vm_pressure_level: 4'
    })
    const m = darwinMemInfo(() => VM_STAT, TOTAL_BYTES, (names) => {
      runs.push(names)
      return both(names)
    })
    expect(runs).toEqual([['vm.swapusage', 'kern.memorystatus_vm_pressure_level']])
    expect(m?.display).toEqual({ swapUsedMb: 7854, swapTotalMb: 9216, pressureLevel: 'critical' })
  })

  it('the one run answers each field from its own line, in either order', () => {
    const reversed = (): string =>
      'kern.memorystatus_vm_pressure_level: 1\n' + SWAPUSAGE
    expect(darwinMemInfo(() => VM_STAT, TOTAL_BYTES, reversed)?.display).toEqual({
      swapUsedMb: 7854,
      swapTotalMb: 9216,
      pressureLevel: 'normal'
    })
  })

  it('adds swap and pressure under `display` and NEVER fills the reaper pair', () => {
    const m = darwinMemInfo(() => VM_STAT, TOTAL_BYTES, sysctl({
      'vm.swapusage': SWAPUSAGE.trimEnd(),
      'kern.memorystatus_vm_pressure_level': 'kern.memorystatus_vm_pressure_level: 2'
    }))
    expect(m).toEqual({
      availableMb: 8951,
      totalMb: 24576,
      display: { swapUsedMb: 7854, swapTotalMb: 9216, pressureLevel: 'warn' }
    })
    // The reaper's Linux swap term reads these; on this Mac (16% free) it would fire all day.
    expect(m).not.toHaveProperty('swapTotalMb')
    expect(m).not.toHaveProperty('swapFreeMb')
  })

  it('a failed sysctl omits only its own field; both failing leaves the vm_stat reading untouched', () => {
    const swapOnly = darwinMemInfo(() => VM_STAT, TOTAL_BYTES, sysctl({ 'vm.swapusage': SWAPUSAGE.trimEnd() }))
    expect(swapOnly?.display).toEqual({ swapUsedMb: 7854, swapTotalMb: 9216 })
    const none = darwinMemInfo(() => VM_STAT, TOTAL_BYTES, sysctl({}))
    expect(none).toEqual({ availableMb: 8951, totalMb: 24576 })
    // vm_stat failing still wins: no reading at all, never a display-only one.
    expect(darwinMemInfo(() => { throw new Error('no vm_stat') }, TOTAL_BYTES, sysctl({ 'vm.swapusage': SWAPUSAGE.trimEnd() }))).toBeNull()
  })

  it.skipIf(process.platform !== 'darwin')('reads this Mac\'s real swap and pressure (darwin-only: sysctl oids)', () => {
    const m = readMemInfo()
    expect(m).not.toBeNull()
    expect(m).not.toHaveProperty('swapTotalMb')
    expect(typeof m?.display?.swapTotalMb).toBe('number')
    expect(['normal', 'warn', 'critical']).toContain(m?.display?.pressureLevel)
  })
})

describe('appSelfMemory — "nodeterm itself"', () => {
  const S = (pid: number, type: string, cpuSeconds?: number): AppProcessSample => ({
    pid,
    type,
    ...(cpuSeconds !== undefined ? { cpuSeconds } : {})
  })
  // The live shape: GPU footprint 1.6 GB while its rss was ~120 MB; two renderers (canvas + HUD).
  const SAMPLES = [S(10, 'Browser', 60), S(11, 'GPU', 3600), S(12, 'Tab', 900), S(13, 'Tab', 5), S(14, 'Utility', 2)]
  const FP = (pid: number, kb: number) => ({ pid, ppid: 1, rssKb: kb, footprint: true as const })
  const TABLE = [FP(10, 180 * 1024), FP(11, 1600 * 1024), FP(12, 300 * 1024), FP(13, 40 * 1024), FP(14, 20 * 1024)]

  it('folds Electron types into gpu / renderer / main / helper, GPU first', () => {
    expect(['Browser', 'Tab', 'GPU', 'Utility', 'Zygote'].map(appProcessKind)).toEqual(['main', 'renderer', 'gpu', 'helper', 'helper'])
    const r = appSelfMemory(SAMPLES, TABLE, 'darwin')
    expect(r).toEqual({
      ok: true,
      groups: [
        { kind: 'gpu', count: 1, mb: 1600, cpuSeconds: 3600 },
        { kind: 'renderer', count: 2, mb: 340, cpuSeconds: 905 },
        { kind: 'main', count: 1, mb: 180, cpuSeconds: 60 },
        { kind: 'helper', count: 1, mb: 20, cpuSeconds: 2 }
      ],
      totalMb: 2140
    })
  })

  it('darwin: a pid top did not cover keeps NO figure — its rss is the blind number this replaces', () => {
    const table = TABLE.map((e) => (e.pid === 11 ? { pid: 11, ppid: 1, rssKb: 120 * 1024 } : e))
    const r = appSelfMemory(SAMPLES, table, 'darwin')
    expect(r.ok).toBe(true)
    expect(r.groups.find((g) => g.kind === 'gpu')).toEqual({ kind: 'gpu', count: 1, cpuSeconds: 3600 })
    // No total over a missing GPU: it would understate by the very 1.5 GB at issue.
    expect(r).not.toHaveProperty('totalMb')
    // Linux / Windows read the table's own accounting (VmRSS / working set) — same as the rows.
    expect(appSelfMemory(SAMPLES, table, 'linux').groups[0]).toMatchObject({ kind: 'gpu', mb: 120 })
  })

  it('a group with one missing pid has no partial sum', () => {
    const r = appSelfMemory(SAMPLES, TABLE.filter((e) => e.pid !== 13), 'darwin')
    expect(r.groups.find((g) => g.kind === 'renderer')).toEqual({ kind: 'renderer', count: 2, cpuSeconds: 905 })
  })

  it('CPU time is omitted, not zeroed, when Electron did not report it', () => {
    const r = appSelfMemory([S(10, 'Browser'), S(11, 'GPU', 7)], TABLE, 'darwin')
    expect(r.groups).toEqual([
      { kind: 'gpu', count: 1, mb: 1600, cpuSeconds: 7 },
      { kind: 'main', count: 1, mb: 180 }
    ])
  })

  it('ok:false — never an empty ok group — when nothing could be measured', () => {
    expect(appSelfMemory(null, TABLE, 'darwin')).toEqual({ ok: false, groups: [] })
    expect(appSelfMemory([], TABLE, 'darwin')).toEqual({ ok: false, groups: [] })
    expect(appSelfMemory(SAMPLES, null, 'darwin')).toEqual({ ok: false, groups: [] })
    expect(appSelfMemory(SAMPLES, [], 'linux')).toEqual({ ok: false, groups: [] })
  })

  it('rides on the tmux sweep\'s own table, and a throwing reader is not-measured', async () => {
    const base = {
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1'],
      exec: async () => 'nt-a|100|claude\n',
      readTable: () => [P(100, 1, 40 * 1024), { pid: 7, ppid: 1, rssKb: 512 * 1024, footprint: true as const }],
      readMem: () => null
    }
    const ok = await collectSessionMemory({ ...base, appProcesses: () => [S(7, 'GPU')] })
    expect(ok.app).toEqual({ ok: true, groups: [{ kind: 'gpu', count: 1, mb: 512 }], totalMb: 512 })
    // The session rows are untouched by it.
    expect(ok.rows.map((r) => r.nodeId)).toEqual(['a'])
    const threw = await collectSessionMemory({ ...base, appProcesses: () => { throw new Error('gone') } })
    expect(threw.app).toEqual({ ok: false, groups: [] })
    // No reader injected (Server Edition) → no field at all: "not available", not "could not measure".
    expect(await collectSessionMemory(base)).not.toHaveProperty('app')
  })
})

describe('which memory measure the rows are in', () => {
  const report = (table: ProcEntry[]): Promise<SessionMemoryReport> =>
    collectSessionMemory({
      tmuxBin: () => '/usr/bin/tmux',
      sockets: ['s1'],
      exec: async () => 'nt-a|100|claude\n',
      readTable: () => table,
      readMem: () => null
    })

  it('says rss (working set on Windows) when the table carries no footprint', async () => {
    expect((await report([P(100, 1, 1024)])).metric).toBe(
      process.platform === 'win32' ? 'working-set' : 'rss'
    )
  })

  it('says footprint when it does', async () => {
    expect((await report([{ ...P(100, 1, 1024), footprint: true }])).metric).toBe('footprint')
  })

  it('says working set for a Windows session host', async () => {
    const r = await collectSessionHostMemory({
      platformName: 'win32',
      list: async () => ({ running: true, names: ['nt-a'], sessions: [{ name: 'nt-a', pid: 100 }] }) as SessionHostListing,
      readTable: async () => [{ ...P(100, 1, 1024), name: 'pwsh.exe' }],
      readMem: () => null
    })
    expect(r.metric).toBe('working-set')
    expect(r.rows[0].largestName).toBe('pwsh.exe')
  })
})

describe.skipIf(process.platform !== 'linux')('the Linux /proc reader', () => {
  it('carries each process name', () => {
    const me = defaultProcessTableReader()?.find((e) => e.pid === process.pid)
    expect(me?.name).toBeTruthy()
  })
})