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.

11.2 KB
Raw Blame
/** Canonical path evidence for a bounded native descriptor pool, including excluded candidates. */
import { lstatSync, readlinkSync, type BigIntStats } from 'node:fs'
import { lstat, readlink } from 'node:fs/promises'
import { dirname, isAbsolute, join, win32 } from 'node:path'
import { NativeEvidenceBudget, nativeUnavailable } from './nativeEvidence.js'
import { hostPlatform } from './windowsFiles.js'

export const nativeFileKey = (info: Pick<BigIntStats, 'dev' | 'ino'>) => `${info.dev}:${info.ino}`
const identity = (info: BigIntStats | null) => info && `${nativeFileKey(info)}:${info.mode}:${info.uid}`
const version = (info: BigIntStats) => `${identity(info)}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`
/** Saved evidence outlives a reboot, and st_dev does not: macOS numbers /dev/diskN as disks appear at boot, so one
 * restart moved a user's data volume from 1,4 to 1,7 and held every launch for good (2026-10-16). Saved identities
 * and versions lead with st_dev; they are compared without it. */
export const withoutDevice = <T extends string | null | undefined>(saved: T): T => (saved && saved.slice(saved.indexOf(':') + 1)) as T
type Part = { info: BigIntStats | null; target?: string }
type Location = { path: string; info: BigIntStats } | null
/** Immutable route facts can cross a service boundary; timestamps matter for aliases, not sibling churn. */
export type NativePathFact = { path: string; identity: string | null; alias?: { target: string; version: string } }
export function verifyNativePathFacts(facts: readonly NativePathFact[]): void {
  const budget = new NativeEvidenceBudget()
  if (!facts.length || facts.length > 256) return nativeUnavailable('the retained route exceeds its limit')
  for (const fact of facts) {
    budget.step()
    if (!isAbsolute(fact.path) || fact.path.includes('\0') || Buffer.byteLength(fact.path) > 4096) {
      return nativeUnavailable('the retained route is invalid')
    }
    let info: BigIntStats | null, target: string | undefined
    try {
      info = lstatSync(fact.path, { bigint: true })
      if (info.isSymbolicLink()) target = readlinkSync(fact.path)
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return nativeUnavailable('the retained route became unreadable')
      info = null
    }
    if (withoutDevice(identity(info)) !== withoutDevice(fact.identity)
      || (fact.alias && (!info || withoutDevice(version(info)) !== withoutDevice(fact.alias.version) || target !== fact.alias.target))) {
      return nativeUnavailable('the retained route changed during preparation')
    }
  }
}

/** NativePaths walks the paths node:path produces, so by default it walks Windows paths when the path module is
 * Windows' and POSIX ones otherwise, not by `process.platform`: a spec that fakes win32 on a POSIX host still has POSIX paths. */
export class NativePaths {
  private readonly parts = new Map<string, Part>()
  private readonly windows: boolean
  constructor(private readonly budget: NativeEvidenceBudget, platform?: NodeJS.Platform) {
    this.windows = (platform ?? hostPlatform()) === 'win32'
  }

  async resolve(path: string, missingOkay = false): Promise<Location> {
    const steps = this.walk(path, missingOkay)
    let next = steps.next()
    while (!next.done) {
      let proof: Part
      try {
        const info = await lstat(next.value, { bigint: true })
        proof = { info, ...(info.isSymbolicLink() ? { target: await readlink(next.value) } : {}) }
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code === 'ENOENT') proof = { info: null }
        else return nativeUnavailable('a native location could not be inspected')
      }
      next = steps.next(proof)
    }
    return next.value
  }

  /** Eager binding and hook admission share exactly the same bounded ancestry rules. */
  resolveSync(path: string, missingOkay = false): Location {
    const steps = this.walk(path, missingOkay)
    let next = steps.next()
    while (!next.done) {
      let proof: Part
      try {
        const info = lstatSync(next.value, { bigint: true })
        proof = { info, ...(info.isSymbolicLink() ? { target: readlinkSync(next.value) } : {}) }
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code === 'ENOENT') proof = { info: null }
        else return nativeUnavailable('a native location could not be inspected')
      }
      next = steps.next(proof)
    }
    return next.value
  }

  snapshot(): NativePathFact[] {
    this.verify()
    return [...this.parts].map(([path, part]) => ({ path, identity: identity(part.info),
      ...(part.target !== undefined ? { alias: { target: part.target, version: version(part.info!) } } : {}) }))
  }

  /** Only an observed absent leaf can be announced before creation. A dangling alias is
   * still an existing leaf and must not borrow the authority of its original parent. */
  absentLeaf(path: string): boolean { return this.parts.get(path)?.info === null }

  /** A reviewed deletion may remove this subtree, never its observed ancestors or aliases.
   * Retain only immutable route facts; every later check receives a fresh bounded budget. */
  retainOutside(removedPath: string): () => void {
    this.budget.step()
    const separator = this.windows ? '\\' : '/'
    const retained = [...this.parts].filter(([path]) => path !== removedPath && !path.startsWith(removedPath + separator))
    return () => {
      const fresh = new NativePaths(new NativeEvidenceBudget(), this.windows ? 'win32' : 'linux')
      for (const [path, part] of retained) fresh.parts.set(path, part)
      fresh.verify()
    }
  }

  private *walk(path: string, missingOkay: boolean): Generator<string, Location, Part> {
    if (this.windows) return yield* this.walkWindows(path, missingOkay)
    if (!isAbsolute(path) || path.includes('\0') || Buffer.byteLength(path) > 4096) return nativeUnavailable('a native location is invalid or exceeds its limit')
    // Follow links in component order. Normalizing bridge/../home first would skip bridge.
    let prefix = '/', pending = path.slice(1).split('/').filter(Boolean), links = 0
    let info: BigIntStats | null = null
    if (!pending.length) pending = ['.']
    for (let index = 0; pending.length; index++) {
      this.budget.step()
      if (index >= 256) return nativeUnavailable('the native path component limit was reached')
      const part = pending.shift()!
      if (part === '..') { prefix = dirname(prefix); if (!pending.length) pending = ['.']; continue }
      if (part === '.' && pending.length) continue
      const next = part === '.' ? prefix : join(prefix, part)
      let proof = this.parts.get(next)
      if (!proof) {
        proof = yield next
        this.parts.set(next, proof)
      }
      info = proof.info
      if (!info) {
        if (missingOkay) return null
        return nativeUnavailable('a native location is missing')
      }
      if (proof.target !== undefined) {
        if (++links > 32) return nativeUnavailable('the native alias depth limit was reached')
        if (isAbsolute(proof.target)) prefix = '/'
        pending = [...proof.target.split('/').filter(Boolean), ...pending]
        if (!pending.length) pending = ['.']
      } else {
        if (pending.length && !info.isDirectory()) return nativeUnavailable('a native path ancestor is not a directory')
        prefix = next
      }
    }
    this.budget.step()
    return { path: prefix, info: info! }
  }

  /**
   * A Windows path: drive-absolute only (`C:\…`), never a UNC share, a device path (`\\?\`, `\\.\`) or a drive-relative
   * one. NTFS gives Node no owner or mode bits to trust a hook file by. What protects it is the profile's ACL and the
   * route itself, so no step may be a link: Harness refuses what Node reports as a symbolic link (symlinks and
   * junctions), and never follows it (spec section 4). `..` is then lexical. A `:` after the drive (an alternate data
   * stream) is refused.
   */
  private *walkWindows(path: string, missingOkay: boolean): Generator<string, Location, Part> {
    if (!/^[A-Za-z]:[\\/]/.test(path) || path.includes('\0') || Buffer.byteLength(path) > 4096) {
      return nativeUnavailable('a native location is invalid or exceeds its limit')
    }
    const steps = [`${path[0].toUpperCase()}:\\`]
    for (const part of path.slice(3).split(/[\\/]/).filter(Boolean)) {
      if (steps.length > 256) return nativeUnavailable('the native path component limit was reached')
      if (part.includes(':')) return nativeUnavailable('a native location is invalid or exceeds its limit')
      if (part === '.') continue
      if (part === '..') { if (steps.length > 1) steps.pop(); continue }
      steps.push(win32.join(steps.at(-1)!, part))
    }
    let info: BigIntStats | null = null
    for (const [index, next] of steps.entries()) {
      this.budget.step()
      let proof = this.parts.get(next)
      if (!proof) {
        proof = yield next
        this.parts.set(next, proof)
      }
      info = proof.info
      if (!info) return missingOkay ? null : nativeUnavailable('a native location is missing')
      if (proof.target !== undefined) return nativeUnavailable('a native location on Windows is a reparse point (a link or junction), which Harness does not follow')
      if (index < steps.length - 1 && !info.isDirectory()) return nativeUnavailable('a native path ancestor is not a directory')
    }
    this.budget.step()
    return { path: steps.at(-1)!, info: info! }
  }

  /** Case/normalization aliases and bind mounts can have different spellings for
   * the same directory. Only the observed physical ancestor chain proves membership. */
  within(path: string, roots: readonly BigIntStats[]): boolean {
    const keys = new Set(roots.map(nativeFileKey))
    const parentOf = this.windows ? win32.dirname : dirname
    for (let parent = parentOf(path);;) {
      this.budget.step()
      const part = this.parts.get(parent)
      if (part?.info && !part.target && part.info.isDirectory() && keys.has(nativeFileKey(part.info))) return true
      // The root (`/`, or a drive's `C:\`) is its own parent.
      if (parentOf(parent) === parent) return false
      if (!part?.info || part.target !== undefined || !part.info.isDirectory()) return nativeUnavailable('the native directory ancestry is incomplete')
      parent = parentOf(parent)
    }
  }

  /** No asynchronous work follows the caller's last header fence. Unrelated directory
   * contents may change; replacing an ordinary ancestor or any alias may not. */
  verify(): void {
    for (const [path, before] of this.parts) {
      this.budget.step()
      let now: BigIntStats | null
      try { now = lstatSync(path, { bigint: true }) }
      catch (error) {
        if ((error as NodeJS.ErrnoException).code === 'ENOENT') now = null
        else return nativeUnavailable('a native location became unreadable')
      }
      let target: string | undefined
      if (before.target !== undefined && now?.isSymbolicLink()) {
        try { target = readlinkSync(path) } catch { return nativeUnavailable('a native alias became unreadable') }
      }
      if (identity(now) !== identity(before.info)
        || (before.target !== undefined && (!now || version(now) !== version(before.info!)
          || target !== before.target))) {
        return nativeUnavailable('a native path or alias changed during inspection')
      }
    }
  }
}