Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

22.0 KB
Raw Blame
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'

const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn() }))

vi.mock('node:child_process', () => ({ execFile: execFileMock }))

import {
  createProcessTableSnapshotReader,
  getProcessTableSnapshot,
  getStrictProcessTableSnapshot,
  getStrictProcessTableSnapshotWithAge,
  PROCESS_TABLE_EVIDENCE_BUDGET_MS,
  PS_MAX_BUFFER_BYTES,
  PS_TIMEOUT_MS,
  resetProcessTableSnapshotForTests
} from './process-table-snapshot-reader'
import {
  parseProcessTableRows,
  parseStrictProcessTableRows,
  ProcessTableCaptureError
} from './process-table-snapshot'
import { buildProcessTableIndex, getProcessTableIndex } from './process-table-index'

function deferred<T>(): {
  promise: Promise<T>
  resolve: (v: T) => void
  reject: (e: unknown) => void
} {
  let resolve!: (v: T) => void
  let reject!: (e: unknown) => void
  const promise = new Promise<T>((res, rej) => {
    resolve = res
    reject = rej
  })
  return { promise, resolve, reject }
}

describe('process-table-snapshot reader', () => {
  it('collapses concurrent calls into a single ps scan', async () => {
    let scans = 0
    const gate = deferred<string>()
    const reader = createProcessTableSnapshotReader({
      runPs: () => {
        scans += 1
        return gate.promise
      },
      now: () => 0
    })

    const a = reader.getSnapshot()
    const b = reader.getSnapshot()
    const c = reader.getSnapshot()
    gate.resolve('ps-output')

    expect(await a).toBe('ps-output')
    expect(await b).toBe('ps-output')
    expect(await c).toBe('ps-output')
    // In-flight sharing must collapse a pane burst into one ps fork.
    expect(scans).toBe(1)
  })

  it('reuses the cached snapshot within the TTL window', async () => {
    let scans = 0
    let clock = 0
    const reader = createProcessTableSnapshotReader({
      runPs: () => {
        scans += 1
        return Promise.resolve(`scan-${scans}`)
      },
      now: () => clock,
      ttlMs: 500
    })

    expect(await reader.getSnapshot()).toBe('scan-1')
    clock = 499
    expect(await reader.getSnapshot()).toBe('scan-1')
    expect(scans).toBe(1)
  })

  it('rescans once the TTL expires', async () => {
    let scans = 0
    let clock = 0
    const reader = createProcessTableSnapshotReader({
      runPs: () => {
        scans += 1
        return Promise.resolve(`scan-${scans}`)
      },
      now: () => clock,
      ttlMs: 500
    })

    expect(await reader.getSnapshot()).toBe('scan-1')
    clock = 500
    expect(await reader.getSnapshot()).toBe('scan-2')
    expect(scans).toBe(2)
  })

  it('stamps capture time after the scan resolves so a slow ps cannot serve a stale snapshot', async () => {
    let scans = 0
    let clock = 0
    const gate = deferred<string>()
    const reader = createProcessTableSnapshotReader({
      runPs: () => {
        scans += 1
        return scans === 1 ? gate.promise : Promise.resolve(`scan-${scans}`)
      },
      now: () => clock,
      ttlMs: 500
    })

    const first = reader.getSnapshot()
    // The scan takes 600ms of wall clock to return — longer than the TTL.
    clock = 600
    gate.resolve('scan-1')
    expect(await first).toBe('scan-1')

    // TTL starts at completion (600), so 900 is still cached.
    clock = 900
    expect(await reader.getSnapshot()).toBe('scan-1')
    expect(scans).toBe(1)
  })

  it('reports the age of the capture instant, not of the moment ps finished', async () => {
    let clock = 0
    const gate = deferred<string>()
    const reader = createProcessTableSnapshotReader({
      runPs: () => gate.promise,
      now: () => clock,
      ttlMs: 500
    })

    const first = reader.getSnapshot()
    // A capture that took 4s of wall clock describes the machine as it was 4s ago.
    clock = 4_000
    gate.resolve('scan-1')
    await first

    // Starting age at completion previously admitted already-stale captures to destructive consumers.
    expect((await reader.getSnapshotWithAge()).capturedAgeMs).toBe(4_000)
  })

  it('reports an older input’s age in whole milliseconds, rounded older, for the integer-only wire', async () => {
    const clock = 10_000
    const reader = createProcessTableSnapshotReader({
      // Recovered argv read 750.5ms before the capture, converted from the monotonic clock.
      runPs: async (_fresh, inputAt) => {
        inputAt(clock - 750.5)
        return 'scan'
      },
      now: () => clock,
      ttlMs: 500
    })

    expect((await reader.getSnapshotWithAge()).capturedAgeMs).toBe(751)
  })

  it('does not cache failures and retries on the next call', async () => {
    let scans = 0
    const reader = createProcessTableSnapshotReader({
      runPs: () => {
        scans += 1
        if (scans === 1) {
          return Promise.reject(new Error('ps timed out'))
        }
        return Promise.resolve('recovered')
      },
      now: () => 0
    })

    await expect(reader.getSnapshot()).rejects.toThrow('ps timed out')
    // Transient failures must clear the cache so the next inspection can recover.
    expect(await reader.getSnapshot()).toBe('recovered')
    expect(scans).toBe(2)
  })

  it('forces a post-request scan even when a same-tick cache exists', async () => {
    let scans = 0
    const reader = createProcessTableSnapshotReader({
      runPs: async () => `scan-${++scans}`,
      now: () => 0
    })

    expect(await reader.getSnapshot()).toBe('scan-1')
    expect(await reader.getFreshSnapshot()).toBe('scan-2')
    expect(scans).toBe(2)
  })

  it('shares same-turn fresh requests but queues one scan after a pre-existing scan', async () => {
    let scans = 0
    const first = deferred<string>()
    const second = deferred<string>()
    const reader = createProcessTableSnapshotReader({
      runPs: () => {
        scans += 1
        return scans === 1 ? first.promise : second.promise
      },
      now: () => 0
    })

    const stale = reader.getSnapshot()
    const freshA = reader.getFreshSnapshot()
    const freshB = reader.getFreshSnapshot()
    expect(scans).toBe(1)
    first.resolve('stale')
    expect(await stale).toBe('stale')
    await Promise.resolve()
    expect(scans).toBe(2)
    second.resolve('fresh')
    expect(await freshA).toBe('fresh')
    expect(await freshB).toBe('fresh')
    expect(scans).toBe(2)
  })

  it('does not let an ordinary same-turn miss race a queued fresh scan', async () => {
    let scans = 0
    const reader = createProcessTableSnapshotReader({
      runPs: async () => `scan-${++scans}`,
      now: () => 0
    })

    const fresh = reader.getFreshSnapshot()
    const ordinary = reader.getSnapshot()

    await expect(Promise.all([fresh, ordinary])).resolves.toEqual(['scan-1', 'scan-1'])
    expect(scans).toBe(1)
  })
})

describe('shared process-table capture', () => {
  beforeEach(() => {
    execFileMock.mockReset()
    resetProcessTableSnapshotForTests()
  })

  function mockPsCaptures(...stdouts: string[]): () => number {
    let forks = 0
    execFileMock.mockImplementation(
      (_command: string, _args: string[], _options: unknown, callback: unknown) => {
        const stdout = stdouts[Math.min(forks, stdouts.length - 1)] ?? ''
        forks += 1
        ;(callback as (err: unknown, result: { stdout: string; stderr: string }) => void)(null, {
          stdout,
          stderr: ''
        })
      }
    )
    return () => forks
  }

  it('serves the strict and lenient views from ONE ps fork per TTL window', async () => {
    // Both views use identical argv; separate caches doubled relay idle forks (#6288).
    const tty = process.platform === 'darwin' ? '??' : '?'
    const forks = mockPsCaptures(
      `100 1 100 100 Ss+ ${tty} Fri Oct 9 12:34:56 2026 /bin/zsh\n`,
      `200 1 200 200 Ss+ ${tty} Fri Oct 9 12:34:56 2026 /bin/bash\n`
    )

    const [lenient, strict] = await Promise.all([
      getProcessTableSnapshot(),
      getStrictProcessTableSnapshot()
    ])

    expect(forks()).toBe(1)
    expect(lenient.map((row) => row.pid)).toEqual([100])
    expect(strict.map((row) => row.pid)).toEqual([100])
  })

  it('reuses the cached capture for a later strict read inside the TTL', async () => {
    const tty = process.platform === 'darwin' ? '??' : '?'
    const forks = mockPsCaptures(
      `100 1 100 100 Ss+ ${tty} Fri Oct 9 12:34:56 2026 /bin/zsh\n`,
      `200 1 200 200 Ss+ ${tty} Fri Oct 9 12:34:56 2026 /bin/bash\n`
    )

    await getProcessTableSnapshot()
    const strict = await getStrictProcessTableSnapshot()

    expect(forks()).toBe(1)
    expect(strict).toEqual([
      {
        pid: 100,
        ppid: 1,
        pgid: 100,
        tpgid: 100,
        stat: 'Ss+',
        tty,
        ...(process.platform === 'linux' ? {} : { startTime: 'Fri Oct 9 12:34:56 2026' }),
        command: '/bin/zsh'
      }
    ])
  })

  it('keeps the lenient view readable when the same capture is strictly unreadable', async () => {
    const forks = mockPsCaptures('100 1 Ss+ /bin/zsh\n')

    const lenient = await getProcessTableSnapshot()
    await expect(getStrictProcessTableSnapshot()).rejects.toBeInstanceOf(ProcessTableCaptureError)

    expect(forks()).toBe(process.platform === 'darwin' ? 2 : 1)
    expect(lenient).toEqual([{ pid: 100, ppid: 1, stat: 'Ss+', command: '/bin/zsh' }])
  })
})

describe('parseProcessTableRows', () => {
  it('parses pid/ppid/stat and keeps the full command (including spaces)', () => {
    const rows = parseProcessTableRows(
      ['501 1 S /bin/zsh', '600 501 S+ node /path/bin/codex --flag'].join('\n')
    )
    expect(rows).toEqual([
      { pid: 501, ppid: 1, stat: 'S', command: '/bin/zsh' },
      {
        pid: 600,
        ppid: 501,
        stat: 'S+',
        command: 'node /path/bin/codex --flag'
      }
    ])
  })

  it('tolerates CRLF and skips header/blank/non-matching lines', () => {
    const rows = parseProcessTableRows('  PID PPID STAT COMMAND\r\n42 1 Ss /sbin/launchd\r\n\r\n')
    expect(rows).toEqual([{ pid: 42, ppid: 1, stat: 'Ss', command: '/sbin/launchd' }])
  })
})

describe('parseStrictProcessTableRows', () => {
  it('accepts Linux kernel roots and bracketed comm values', () => {
    const capture = readFileSync(
      join(__dirname, '__fixtures__', 'linux-process-table-kernel-rows.txt'),
      'utf8'
    )
    expect(parseStrictProcessTableRows(capture)).toEqual([
      { pid: 1, ppid: 0, pgid: 1, tpgid: 0, stat: 'Ss', command: '/sbin/init' },
      { pid: 2, ppid: 0, pgid: 0, tpgid: -1, stat: 'S', command: '[kthreadd]' },
      {
        pid: 3,
        ppid: 2,
        pgid: 0,
        tpgid: -1,
        stat: 'I',
        command: '[pool_workqueue_release]'
      },
      {
        pid: 4,
        ppid: 2,
        pgid: 0,
        tpgid: -1,
        stat: 'I',
        command: '[kworker/R-rcu_g]'
      },
      {
        pid: 5,
        ppid: 2,
        pgid: 0,
        tpgid: -1,
        stat: 'I',
        command: '[kworker/R-sync_wq]'
      },
      {
        pid: 6,
        ppid: 2,
        pgid: 0,
        tpgid: -1,
        stat: 'I',
        command: '[kworker/R-slub_]'
      },
      {
        pid: 100,
        ppid: 1,
        pgid: 100,
        tpgid: 100,
        stat: 'Ss+',
        command: '/bin/bash -l'
      },
      {
        pid: 101,
        ppid: 100,
        pgid: 101,
        tpgid: 101,
        stat: 'S+',
        command: 'node /opt/codex'
      }
    ])
  })

  it('extracts pgid/tpgid across CRLF framing while retaining command spacing', () => {
    expect(
      parseStrictProcessTableRows(
        ' PID PPID PGID TPGID STAT COMMAND\r\n 100 1 100 101 Ss /bin/zsh -l\r\n 101 100 101 101 S+ node /opt/codex --flag  value\r\n'
      )
    ).toEqual([
      {
        pid: 100,
        ppid: 1,
        pgid: 100,
        tpgid: 101,
        stat: 'Ss',
        command: '/bin/zsh -l'
      },
      {
        pid: 101,
        ppid: 100,
        pgid: 101,
        tpgid: 101,
        stat: 'S+',
        command: 'node /opt/codex --flag  value'
      }
    ])
  })

  it('accepts no-controlling-tty sentinels for later unverifiable classification', () => {
    expect(parseStrictProcessTableRows('100 1 100 0 Ss /bin/zsh')).toEqual([
      {
        pid: 100,
        ppid: 1,
        pgid: 100,
        tpgid: 0,
        stat: 'Ss',
        command: '/bin/zsh'
      }
    ])
    expect(parseStrictProcessTableRows('100 1 100 -1 Ss /bin/zsh')).toEqual([
      {
        pid: 100,
        ppid: 1,
        pgid: 100,
        tpgid: -1,
        stat: 'Ss',
        command: '/bin/zsh'
      }
    ])
  })

  it('still rejects truncated captures as unreadable', () => {
    expect(() => parseStrictProcessTableRows('100 1 100 100 Ss+')).toThrow(ProcessTableCaptureError)
  })

  it.each([
    '0 0 0 0 S [invalid-pid]',
    '100 1 -1 100 S [invalid-pgid]',
    '100 1 100 -2 S [invalid-tpgid]'
  ])('rejects domain-invalid numeric values (%s)', (capture) => {
    expect(() => parseStrictProcessTableRows(capture)).toThrow(ProcessTableCaptureError)
  })

  it('rejects an empty or header-only capture as unreadable', () => {
    expect(() => parseStrictProcessTableRows('')).toThrow(ProcessTableCaptureError)
    expect(() => parseStrictProcessTableRows('PID PPID PGID TPGID STAT COMMAND')).toThrow(
      ProcessTableCaptureError
    )
  })
})

describe('getProcessTableIndex', () => {
  it('reuses one index for the same snapshot identity', () => {
    const rows = parseProcessTableRows(
      ['100 1 Ss bash', '101 100 S node codex', '102 100 S vim'].join('\n')
    )

    const first = getProcessTableIndex(rows)
    const second = getProcessTableIndex(rows)

    expect(second).toBe(first)
    expect(first.byPid.get(100)).toBe(rows[0])
    expect(first.childrenByPpid.get(100)).toEqual([rows[1], rows[2]])
  })

  it('does not reuse an index across distinct snapshot arrays', () => {
    const firstRows = parseProcessTableRows('100 1 Ss bash')
    const secondRows = parseProcessTableRows('100 1 Ss bash')

    expect(getProcessTableIndex(secondRows)).not.toBe(getProcessTableIndex(firstRows))
  })

  it('resolves a duplicated pid to the FIRST row, as `rows.find()` did', () => {
    // Keep the first row like rows.find: argv newlines can create later spurious duplicate-PID rows.
    const rows = parseProcessTableRows(['100 1 Ss bash', '100 1 Ss+ zsh'].join('\n'))

    expect(getProcessTableIndex(rows).byPid.get(100)).toBe(rows[0])
    expect(buildProcessTableIndex(rows).byPid.get(100)).toBe(rows[0])
  })
})

describe('process-table capture completeness', () => {
  const NODE_DEFAULT_MAX_BUFFER_BYTES = 1024 * 1024

  beforeEach(() => {
    execFileMock.mockReset()
    resetProcessTableSnapshotForTests()
  })

  /** Emulate Node’s maxBuffer kill/error plus truncated bytes; always-resolving mocks would hide the actual ceiling. */
  function mockPsWithNodeBufferSemantics(stdout: string): void {
    execFileMock.mockImplementation(
      (_command: string, _args: string[], options: unknown, callback: unknown) => {
        const done = callback as (err: unknown, result: { stdout: string; stderr: string }) => void
        const maxBuffer =
          (options as { maxBuffer?: number })?.maxBuffer ?? NODE_DEFAULT_MAX_BUFFER_BYTES
        if (Buffer.byteLength(stdout, 'utf-8') > maxBuffer) {
          const error = Object.assign(new Error('stdout maxBuffer length exceeded'), {
            code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
          })
          done(error, { stdout: stdout.slice(0, maxBuffer), stderr: '' })
          return
        }
        done(null, { stdout, stderr: '' })
      }
    )
  }

  function busyHostTable(processCount: number): string {
    // ~285 bytes/row, so 4k processes clears 1MB the way a real busy host does.
    const argv = `/usr/bin/node ${'--inspect-brk-and-a-long-flag '.repeat(8)}server.js`
    return `${Array.from(
      { length: processCount },
      (_, index) => `${1000 + index} 1 ${1000 + index} ${1000 + index} S+ ${argv}`
    ).join('\n')}\n`
  }

  it('reads a busy host whose table overflows execFile 1MB default', async () => {
    const table = busyHostTable(4_000)
    expect(Buffer.byteLength(table, 'utf-8')).toBeGreaterThan(NODE_DEFAULT_MAX_BUFFER_BYTES)
    mockPsWithNodeBufferSemantics(table)

    // Default maxBuffer rejects on busy hosts, making every capture unverifiable until load falls.
    await expect(getProcessTableSnapshot()).resolves.toHaveLength(4_000)
  })

  it('reports a truncated capture as unreadable rather than a silently short table', async () => {
    const table = busyHostTable(200)
    const truncated = table + 'x'.repeat(PS_MAX_BUFFER_BYTES - table.length)
    // The lenient parser accepts truncated rows; strict capture checks must reject partial tables instead of falsely proving no agent.
    expect(parseProcessTableRows(truncated)).toHaveLength(200)
    execFileMock.mockImplementation(
      (_command: string, _args: string[], _options: unknown, callback: unknown) => {
        ;(callback as (err: unknown, result: { stdout: string; stderr: string }) => void)(null, {
          stdout: truncated,
          stderr: ''
        })
      }
    )

    await expect(getProcessTableSnapshot()).rejects.toThrow(ProcessTableCaptureError)
    await expect(getProcessTableSnapshot()).rejects.toThrow('capture_truncated')
  })

  it('names a buffer-ceiling rejection as truncation on both views', async () => {
    mockPsWithNodeBufferSemantics('x'.repeat(PS_MAX_BUFFER_BYTES + 1))

    await expect(getProcessTableSnapshot()).rejects.toThrow('capture_truncated')
    resetProcessTableSnapshotForTests()
    await expect(getStrictProcessTableSnapshot()).rejects.toThrow('capture_truncated')
  })

  it('reports an empty capture as unreadable rather than an empty process table', async () => {
    // An empty table cannot describe a host running ps; lenient [] previously claimed absence.
    execFileMock.mockImplementation(
      (_command: string, _args: string[], _options: unknown, callback: unknown) => {
        ;(callback as (err: unknown, result: { stdout: string; stderr: string }) => void)(null, {
          stdout: '   \n',
          stderr: ''
        })
      }
    )

    await expect(getProcessTableSnapshot()).rejects.toThrow(ProcessTableCaptureError)
    await expect(getProcessTableSnapshot()).rejects.toThrow('empty_capture')
  })

  /** Emulate Node timeout SIGTERM/callback with empty stderr; otherwise a too-short budget looks identical to broken ps. */
  function mockPsTakingMs(durationMs: number, stdout: string): void {
    execFileMock.mockImplementation(
      (command: string, args: string[], options: unknown, callback: unknown) => {
        const done = callback as (err: unknown, result: { stdout: string; stderr: string }) => void
        const timeout = (options as { timeout?: number })?.timeout
        if (timeout !== undefined && durationMs > timeout) {
          const error = Object.assign(
            new Error(`Command failed: ${[command, ...args].join(' ')}\n`),
            { code: null, killed: true, signal: 'SIGTERM' }
          )
          done(error, { stdout: '', stderr: '' })
          return
        }
        done(null, { stdout, stderr: '' })
      }
    )
  }

  it('reads a loaded host whose whole-machine ps runs for seconds', async () => {
    // Measured command= costs 1.15s idle and up to 6s at load 27; 3s killed 6/20 otherwise readable captures.
    mockPsTakingMs(6_000, busyHostTable(200))

    expect(PS_TIMEOUT_MS).toBeGreaterThan(6_000)
    await expect(getProcessTableSnapshot()).resolves.toHaveLength(200)
  })

  it('still bounds a ps that never returns', async () => {
    mockPsTakingMs(PS_TIMEOUT_MS + 1, busyHostTable(200))

    await expect(getProcessTableSnapshot()).rejects.toThrow('Command failed: ps')
  })
})

/** Evidence freshness has a shorter budget than identity proof: stale observations return prompt unverifiable;
 * identity probes wait PS_TIMEOUT_MS because slow captures cannot prove process absence. */
describe('evidence-publishing capture budget', () => {
  beforeEach(() => {
    execFileMock.mockReset()
    resetProcessTableSnapshotForTests()
    vi.useFakeTimers()
  })

  afterEach(() => {
    vi.useRealTimers()
  })

  /** A `ps` that answers after `durationMs` of wall clock, the way a loaded host does. */
  function mockPsTaking(
    durationMs: number,
    stdout = `1 0 1 1 S+ ${process.platform === 'darwin' ? '??' : '?'} Thu Jan 1 00:00:00 2026 bash\n`
  ) {
    execFileMock.mockImplementation(
      (_command: string, _args: string[], _options: unknown, callback: unknown) => {
        const done = callback as (err: unknown, result: { stdout: string; stderr: string }) => void
        setTimeout(() => done(null, { stdout, stderr: '' }), durationMs)
      }
    )
  }

  it('answers from a capture that lands one tick inside the budget', async () => {
    mockPsTaking(PROCESS_TABLE_EVIDENCE_BUDGET_MS - 1)
    const pending = getStrictProcessTableSnapshotWithAge()
    const settled = pending.catch(() => undefined)

    await vi.advanceTimersByTimeAsync(PROCESS_TABLE_EVIDENCE_BUDGET_MS)
    await settled

    // Capture duration counts against 2s freshness; this budget must be far below the identity timeout.
    expect((await pending).capturedAgeMs).toBe(PROCESS_TABLE_EVIDENCE_BUDGET_MS - 1)
  })

  it('gives up on a capture one tick past the budget instead of waiting out PS_TIMEOUT_MS', async () => {
    mockPsTaking(PROCESS_TABLE_EVIDENCE_BUDGET_MS + 1)
    const pending = getStrictProcessTableSnapshotWithAge()
    const settled = pending.then(
      () => 'resolved',
      (error: Error) => error.message
    )

    await vi.advanceTimersByTimeAsync(PROCESS_TABLE_EVIDENCE_BUDGET_MS)

    expect(await settled).toContain('process table unreadable')
  })

  it('leaves the abandoned capture running to fill the cache for the next reader', async () => {
    // Loaded hosts cannot afford a second whole-machine ps; abandoned shared captures must keep filling the cache.
    mockPsTaking(PROCESS_TABLE_EVIDENCE_BUDGET_MS + 100)
    const abandoned = getStrictProcessTableSnapshotWithAge().catch(() => null)

    await vi.advanceTimersByTimeAsync(PROCESS_TABLE_EVIDENCE_BUDGET_MS)
    expect(await abandoned).toBeNull()

    await vi.advanceTimersByTimeAsync(100)
    expect(await getStrictProcessTableSnapshotWithAge()).toMatchObject({
      capturedAgeMs: PROCESS_TABLE_EVIDENCE_BUDGET_MS + 100
    })
    expect(execFileMock).toHaveBeenCalledTimes(1)
  })
})