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.

4.3 KB
Raw Blame
/** One native lookup owns one work budget, including its final verification. */
import { execFile } from 'node:child_process'
import { constants } from 'node:fs'
import { open } from 'node:fs/promises'
import { performance } from 'node:perf_hooks'
import { psEnv } from '../../lib/childLocale.js'
import { IdentityReadUnavailable } from './identityScan.js'

export const nativeUnavailable = (reason: string): never => { throw new IdentityReadUnavailable(reason) }

/**
 * How long one native lookup may take on the wall clock: 3 s, for every lookup. It caps a stuck disk, not a
 * healthy one, which answers in milliseconds. Path, hook-file, installation and engine-home lookups had
 * 250 ms, and on a loaded machine the event loop alone took longer: CI runners and a Mac at load 40 held
 * healthy installations and handoffs as unavailable (2026-10-11).
 */
export const NATIVE_EVIDENCE_MS = 3_000

export class NativeEvidenceBudget {
  private readonly deadline: number
  private operations = 32_768
  private bytes = 16 * 1024 * 1024
  private probes = 64
  constructor(timeoutMs = NATIVE_EVIDENCE_MS) { this.deadline = performance.now() + timeoutMs }
  remaining(): number {
    const left = Math.floor(this.deadline - performance.now())
    if (left <= 0) nativeUnavailable('the native process evidence deadline was reached')
    return left
  }
  step(bytes = 0): void {
    this.remaining()
    if (--this.operations < 0 || (this.bytes -= bytes) < 0) nativeUnavailable('the native process evidence work limit was reached')
  }
  probe(): number {
    this.step()
    if (--this.probes < 0) nativeUnavailable('the native process probe limit was reached')
    return this.remaining()
  }
}

/** Error plus a readable prefix still means that the probe did not finish. */
export async function nativeProbe(command: 'ps' | 'lsof', args: string[], budget: NativeEvidenceBudget,
  maxBuffer = 512 * 1024,
): Promise<string> {
  const timeout = budget.probe()
  const bytes = await new Promise<Buffer>((resolve, reject) => {
    execFile(command, args, { encoding: 'buffer', timeout, killSignal: 'SIGKILL', maxBuffer,
      env: psEnv({ ...process.env, LC_ALL: '', LC_CTYPE: process.platform === 'darwin' ? 'UTF-8' : 'C.UTF-8' }),
    }, (error, stdout, stderr) => {
      if (error || stderr.length) { reject(new IdentityReadUnavailable(`the native ${command} probe did not complete`)); return }
      resolve(stdout)
    })
  }).catch((error: unknown) => {
    if (error instanceof IdentityReadUnavailable) throw error
    return nativeUnavailable(`the native ${command} probe could not start`)
  })
  budget.step(bytes.length)
  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes) }
  catch { return nativeUnavailable(`the native ${command} output is not complete UTF-8`) }
}

/** /proc reports zero file sizes. Read to a bounded EOF rather than trusting that size. */
export async function nativeBytes(path: string, maxBytes: number, budget: NativeEvidenceBudget): Promise<Buffer> {
  budget.step()
  let handle
  try {
    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
    if (!(await handle.stat()).isFile()) nativeUnavailable('a native process record is not a regular file')
    const chunks: Buffer[] = []
    let total = 0
    for (let calls = 0; calls < 64; calls++) {
      budget.step()
      const buffer = Buffer.alloc(Math.min(4096, maxBytes + 1 - total))
      const read = await handle.read(buffer, 0, buffer.length, total)
      budget.step(read.bytesRead)
      if (!read.bytesRead) return Buffer.concat(chunks, total)
      total += read.bytesRead
      if (total > maxBytes) nativeUnavailable('a native process record exceeds its byte limit')
      chunks.push(buffer.subarray(0, read.bytesRead))
    }
    return nativeUnavailable('a native process record exceeds its read-operation limit')
  } catch (error) {
    if (error instanceof IdentityReadUnavailable) throw error
    return nativeUnavailable('a native process record could not be read completely')
  } finally { await handle?.close().catch(() => nativeUnavailable('a native process record could not be closed')) }
}

export function nativeText(bytes: Buffer): string {
  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes) }
  catch { return nativeUnavailable('a native process record is not complete UTF-8') }
}