Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

15.4 KB
Raw Blame
/** Joined, bounded kernel evidence for control. Discovery's partial image reader is not authority. */
import { execFile } from 'node:child_process'
import { constants, closeSync, fstatSync, openSync, opendirSync, readlinkSync, readSync, statSync } from 'node:fs'
import { IdentityReadUnavailable, REPLACED_PROGRAM } from '../engines/kit/identityScan.js'
import type { NativeDescriptor } from '../engines/kit/nativeDescriptors.js'
import { NativeEvidenceBudget, nativeText, nativeUnavailable } from '../engines/kit/nativeEvidence.js'
import { bundledProcessImageHelper, invalidateProcessImageHelper, parseNativeProcessImages } from './nativeProcessImages.js'
import { psEnv } from './childLocale.js'

export interface NativeControlRow {
  pid: number
  parentPid: number
  command: string
  imagePath: string
  argv?: readonly string[]
  commandDigest?: string
  birth: string
  fds: readonly NativeDescriptor[]
}
export interface NativeControlSnapshot {
  parent: number
  children: readonly number[]
  rows: ReadonlyMap<number, NativeControlRow>
}
export const controlIdentity = (row: Omit<NativeControlRow, 'fds'>) =>
  JSON.stringify([row.pid, row.parentPid, row.birth, row.command, row.imagePath, row.argv ?? null, row.commandDigest ?? null])
const validPid = (pid: unknown): pid is number => Number.isInteger(pid) && Number(pid) > 0 && Number(pid) <= 0x7fffffff
const sorted = (pids: readonly number[]) => [...pids].sort((a, b) => a - b).join(',')
const uint = (value: unknown, max: number) => Number.isSafeInteger(value) && Number(value) >= 0 && Number(value) <= max

/** lsof's socket family is immaterial to file ownership; every numeric FD remains in the pool. */
export function controlDescriptors(rows: readonly NativeDescriptor[]): string {
  return rows.filter(row => /^\d+$/.test(row.fd)).map(row => process.platform === 'darwin'
    ? JSON.stringify([row.fd, /^(?:unix|IPv[46]|systm|NDRV|LINK|SOCKET)$/.test(row.kind) ? 'SOCKET' : row.kind,
      String(row.device), String(row.inode)])
    : JSON.stringify([row.fd, row.path, row.kind, String(row.device), String(row.inode)])).sort().join('\n')
}

function hex(value: unknown, max: number, allowNul = false): string {
  if (typeof value !== 'string' || !value.length || value.length > max * 2 || value.length % 2 || !/^[a-f0-9]+$/.test(value)) {
    return nativeUnavailable('the native control reply contains invalid bytes')
  }
  const text = nativeText(Buffer.from(value, 'hex'))
  if (!allowNul && text.includes('\0')) return nativeUnavailable('the native control reply contains an invalid string')
  return text
}

/** No prefixes, duplicate/missing rows, permissive JSON types or rounded inode numbers. */
export function parseNativeProcessControl(output: string, pids: readonly number[], parent: number,
  budget: NativeEvidenceBudget,
): NativeControlSnapshot {
  if (!output.endsWith('\n') || Buffer.byteLength(output) > 5 * 1024 * 1024) return nativeUnavailable('the native control reply is incomplete')
  const lines = output.slice(0, -1).split('\n'), rows = new Map<number, NativeControlRow>()
  if (lines.length !== pids.length + 1) return nativeUnavailable('the native control reply has an incomplete process pool')
  const json = (text: string) => { try { return JSON.parse(text) } catch { return nativeUnavailable('the native control reply is malformed') } }
  const header = json(lines.shift()!)
  if (header?.schema !== 2 || header.mode !== 'control' || header.parent !== parent || !Array.isArray(header.children)
    || header.children.length > 32 || header.children.some((pid: unknown) => !validPid(pid) || pid === parent)
    || new Set(header.children).size !== header.children.length || (!parent && header.children.length)) {
    return nativeUnavailable('the native control reply has an ambiguous child pool')
  }
  let fds = 0
  for (const line of lines) {
    budget.step()
    const row = json(line)
    if (!row || !validPid(row.pid) || !pids.includes(row.pid) || rows.has(row.pid) || !uint(row.parentPid, 0x7fffffff)
      || !uint(row.startSeconds, Number.MAX_SAFE_INTEGER) || !row.startSeconds || !uint(row.startMicros, 999_999)
      || typeof row.commandDigest !== 'string' || !/^[a-f0-9]{64}$/.test(row.commandDigest)
      || !Array.isArray(row.fds) || (fds += row.fds.length) > 4096) {
      return nativeUnavailable('the native control reply has an invalid process record')
    }
    const command = hex(row.commandHex, 16), imagePath = hex(row.imageHex, 4095)
    if (!imagePath.startsWith('/') || imagePath.endsWith(' (deleted)')) {
      return nativeUnavailable('the native control command is incomplete')
    }
    const descriptors: NativeDescriptor[] = [], seen = new Set<number>()
    for (const fd of row.fds) {
      budget.step()
      if (!fd || !uint(fd.fd, 0x7fffffff) || seen.has(fd.fd) || !uint(fd.type, 11) || fd.type === 8
        || !uint(fd.mode, 0xffff) || typeof fd.device !== 'string' || !/^\d{1,10}$/.test(fd.device)
        || BigInt(fd.device) > 0xffffffffn || typeof fd.inode !== 'string' || !/^\d{1,20}$/.test(fd.inode)
        || BigInt(fd.inode) > 0xffffffffffffffffn) return nativeUnavailable('the native control descriptor is invalid')
      seen.add(fd.fd)
      const kinds: Record<number, string> = { 2: 'SOCKET', 3: 'PSXSHM', 4: 'PSXSEM', 5: 'KQUEUE', 6: 'PIPE', 7: 'FSEVENT', 9: 'NPOLICY' }
      const modes: Record<number, string> = { [0o100000]: 'REG', [0o040000]: 'DIR', [0o020000]: 'CHR', [0o060000]: 'BLK', [0o010000]: 'FIFO' }
      const kind = fd.type === 1 ? modes[fd.mode] : kinds[fd.type]
      if (!kind || (fd.type === 1 ? fd.inode === '0' : fd.mode !== 0 || fd.device !== '0' || fd.inode !== '0')) {
        return nativeUnavailable('the native control descriptor type is unavailable')
      }
      descriptors.push({ fd: String(fd.fd), path: '', kind,
        ...(fd.type === 1 ? { device: BigInt(fd.device), inode: BigInt(fd.inode) } : {}) })
    }
    rows.set(row.pid, { pid: row.pid, parentPid: row.parentPid, command, imagePath, commandDigest: row.commandDigest,
      birth: `${row.startSeconds}:${row.startMicros}`, fds: descriptors })
  }
  return { parent, children: header.children, rows }
}

export function linuxProcessStat(text: string, pid: number): { command: string; parentPid: number; state: string; startTicks: number } {
  const start = text.indexOf('('), end = text.lastIndexOf(')')
  if (start < 1 || end <= start || Number(text.slice(0, start).trim()) !== pid) return nativeUnavailable('the native process generation is malformed')
  const fields = text.slice(end + 1).trim().split(/\s+/), startTicks = Number(fields[19])
  if (!/^[A-Za-z]$/.test(fields[0] ?? '') || !/^\d+$/.test(fields[1] ?? '') || !uint(Number(fields[1]), 0x7fffffff)
    || !/^\d+$/.test(fields[19] ?? '') || !Number.isSafeInteger(startTicks)) return nativeUnavailable('the native process generation is incomplete')
  return { command: text.slice(start + 1, end), parentPid: Number(fields[1]), state: fields[0], startTicks }
}

function linuxControl(pids: readonly number[], parent: number, budget: NativeEvidenceBudget): NativeControlSnapshot {
  const bytes = (path: string, limit: number) => {
    budget.step()
    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK)
    try {
      if (!fstatSync(fd).isFile()) return nativeUnavailable('a native process record is not regular')
      const result = Buffer.alloc(limit + 1)
      let used = 0
      for (let calls = 0; calls < 64; calls++) {
        budget.step()
        const count = readSync(fd, result, used, Math.min(4096, result.length - used), used)
        budget.step(count); used += count
        if (used > limit) return nativeUnavailable('a native process record exceeds its byte limit')
        if (!count) return nativeText(result.subarray(0, used))
      }
      return nativeUnavailable('a native process record exceeds its read limit')
    } finally { closeSync(fd) }
  }
  const entries = (path: string, limit: number) => {
    budget.step()
    const directory = opendirSync(path, { bufferSize: 32 }), names: string[] = []
    try {
      for (;;) {
        budget.step()
        const next = directory.readSync()
        if (!next) return names
        if (!/^\d+$/.test(next.name) || names.length >= limit) return nativeUnavailable('the native directory pool exceeds its limit')
        names.push(next.name)
      }
    } finally { directory.closeSync() }
  }
  const stat = (pid: number) => linuxProcessStat(bytes(`/proc/${pid}/stat`, 8192), pid)
  const children = () => {
    if (!parent) return []
    const tasks = entries(`/proc/${parent}/task`, 128), ids: number[] = []
    if (!tasks.length) return nativeUnavailable('the native task pool is empty')
    // In thread order, as /proc lists them: a directory read elsewhere (a test's tmpfs, a hashed ext4) lists in
    // its own order, and the children came back in it (CI, 2026-10-20: [44, 43] for [43, 44]).
    for (const task of [...tasks].sort((a, b) => Number(a) - Number(b))) {
      const text = bytes(`/proc/${parent}/task/${task}/children`, 1024)
      if (!/^(?:\d+\s+)*$/.test(text)) return nativeUnavailable('the native child pool is malformed')
      for (const value of text.trim().split(/\s+/).filter(Boolean)) {
        const id = Number(value)
        if (!validPid(id) || ids.includes(id) || ids.length >= 32) return nativeUnavailable('the native child pool exceeds its limit or is ambiguous')
        const info = stat(id)
        if (info.parentPid !== parent) return nativeUnavailable('the native child changed parent')
        if (!/^[ZXx]/.test(info.state)) ids.push(id)
      }
    }
    if (entries(`/proc/${parent}/task`, 128).sort().join(',') !== tasks.sort().join(',')) return nativeUnavailable('the native task pool changed')
    return ids
  }
  const metadata = (pid: number) => {
    const before = stat(pid)
    if (/^[ZXx]/.test(before.state)) return nativeUnavailable('the native process has exited')
    budget.step()
    const imagePath = readlinkSync(`/proc/${pid}/exe`), args = bytes(`/proc/${pid}/cmdline`, 65_536)
    const after = stat(pid)
    budget.step()
    if (before.parentPid !== after.parentPid || before.startTicks !== after.startTicks || before.command !== after.command
      || /^[ZXx]/.test(after.state) || readlinkSync(`/proc/${pid}/exe`) !== imagePath) return nativeUnavailable('the native process changed during control inspection')
    if (!imagePath.startsWith('/') || imagePath.endsWith(' (deleted)') || !args.endsWith('\0') || !args[0] || args[0] === '\0') return nativeUnavailable('the native process command is incomplete')
    return { pid, parentPid: before.parentPid, command: before.command, imagePath, argv: args.slice(0, -1).split('\0'), birth: String(before.startTicks) }
  }
  const read = () => {
    const rows = new Map<number, NativeControlRow>()
    let total = 0
    for (const pid of pids) {
      const before = metadata(pid), fds: NativeDescriptor[] = []
      for (const fd of entries(`/proc/${pid}/fd`, 4096)) {
        budget.step()
        if (++total > 4096) return nativeUnavailable('the native descriptor pool exceeds its limit')
        const location = `/proc/${pid}/fd/${fd}`, path = readlinkSync(location)
        budget.step(Buffer.byteLength(path))
        if (path.startsWith('/')) {
          const info = statSync(location, { bigint: true })
          fds.push({ fd, path, kind: info.isFile() ? 'REG' : 'OTHER', device: info.dev, inode: info.ino })
        } else {
          if (!/^(?:socket:\[\d+\]|pipe:\[\d+\]|anon_inode:.*)$/.test(path)) return nativeUnavailable('a native descriptor target is unreadable')
          fds.push({ fd, path, kind: 'OTHER' })
        }
      }
      if (controlIdentity(metadata(pid)) !== controlIdentity(before)) return nativeUnavailable('the native process changed around its descriptors')
      rows.set(pid, { ...before, fds })
    }
    return rows
  }
  try {
    const firstChildren = children(), first = read(), rows = read()
    if (sorted(children()) !== sorted(firstChildren)) return nativeUnavailable('the native child pool changed during control inspection')
    for (const [pid, row] of first) {
      const now = rows.get(pid)!
      if (controlIdentity(now) !== controlIdentity(row) || controlDescriptors(now.fds) !== controlDescriptors(row.fds)) return nativeUnavailable('the native control evidence changed during inspection')
    }
    budget.step()
    return { parent, children: firstChildren, rows }
  } catch (error) {
    if (error instanceof IdentityReadUnavailable) throw error
    return nativeUnavailable('the native control evidence could not be read completely')
  }
}

/** A live process with no kernel image path cannot show control evidence until it restarts. */
async function replacedImage(path: string, pids: readonly number[], budget: NativeEvidenceBudget): Promise<boolean> {
  try {
    const timeout = Math.min(budget.probe(), 1000)
    const stdout = await new Promise<string>(resolve => {
      execFile(path, ['--paths', ...pids.map(String)], { encoding: 'utf8', timeout, maxBuffer: 1024 * 1024, killSignal: 'SIGKILL', env: psEnv() },
        (_error, out) => resolve(typeof out === 'string' ? out : ''))
    })
    const { unavailable } = parseNativeProcessImages(stdout, new Set(pids))
    return [...unavailable].some(pid => { try { process.kill(pid, 0); return true } catch { return false } })
  } catch { return false }
}

/** No ps/lsof wait separates the last process and descriptor observations. This does not
 * freeze an external process; immutable core ownership is still checked by every caller. */
export async function nativeProcessControl(pids: readonly number[], parent: number, budget: NativeEvidenceBudget): Promise<NativeControlSnapshot> {
  if (!pids.length || pids.length > 33 || pids.some(pid => !validPid(pid)) || new Set(pids).size !== pids.length
    || (parent !== 0 && (!validPid(parent) || !pids.includes(parent)))) return nativeUnavailable('the native control request is invalid')
  if (process.platform === 'linux') return linuxControl(pids, parent, budget)
  if (process.platform !== 'darwin') return nativeUnavailable('native control evidence is unavailable on this platform')
  let timer: ReturnType<typeof setTimeout> | undefined
  let probeFailed: string | undefined
  try {
    const helper = await Promise.race([bundledProcessImageHelper({ retryUnavailable: true }), new Promise<null>(resolve => {
      timer = setTimeout(() => resolve(null), budget.remaining())
    })])
    if (!helper) return nativeUnavailable('the native control helper is unavailable')
    const timeout = budget.probe()
    const bytes = await new Promise<Buffer>((resolve, reject) => {
      execFile(helper.path, ['--control', String(Math.min(timeout, 3000)), String(parent), ...pids.map(String)],
        { encoding: 'buffer', timeout, maxBuffer: 5 * 1024 * 1024, killSignal: 'SIGKILL', env: psEnv() },
        (error, stdout, stderr) => {
          if (error && ['ENOENT', 'ENOTDIR', 'EACCES', 'ENOEXEC'].includes(String(error.code))) invalidateProcessImageHelper(helper.key)
          if (error || stderr.length) {
            probeFailed = helper.path
            reject(new IdentityReadUnavailable('the native control probe did not complete'))
          }
          else resolve(stdout)
        })
    })
    budget.step(bytes.length)
    return parseNativeProcessControl(nativeText(bytes), pids, parent, budget)
  } catch (error) {
    if (probeFailed && await replacedImage(probeFailed, pids, budget)) {
      throw new IdentityReadUnavailable(REPLACED_PROGRAM)
    }
    if (error instanceof IdentityReadUnavailable) throw error
    return nativeUnavailable('the native control probe could not start')
  } finally { if (timer) clearTimeout(timer) }
}