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.

14.5 KB
Raw Blame
/** A launch resolves once, then keeps that executable through probes and dispatch. */
import { execFile } from 'node:child_process'
import { accessSync, closeSync, constants, lstatSync, openSync, readSync, statSync } from 'node:fs'
import { homedir } from 'node:os'
import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path'
import { engineBin, enginePathOverride } from '../../lib/engineBin.js'
import { engineInstallPaths, engineInstallRecipe, type EngineInstallRecipe } from '../../lib/engineInstall.js'
import { engineShellArgv, interactiveEngineShell, npmRuntimeBins } from '../../lib/engineLaunch.js'
import { managedNodePath } from '../../lib/nodeRuntime.js'
import { probeExecFile } from '../../lib/offThreadExec.js'
import { shellSingleQuote } from '../../lib/shellQuote.js'
import { LAUNCH_LOCATION_VARIABLES } from './nativeLocations.js'
import type { AgentEngine } from '../types.js'
import { NativeEvidenceBudget } from './nativeEvidence.js'
import { NativePaths } from './nativePaths.js'
import { executableSnapshot, nativeVersionProbe, type NativeExecutableSnapshot } from './nativeVersion.js'

export type LaunchExecutableResult =
  | { state: 'ready'; executable: NativeExecutableSnapshot; environment: NodeJS.ProcessEnv }
  | { state: 'install'; recipe: EngineInstallRecipe; environment: Record<string, string> }
  | { state: 'held'; detail: string }
const held = (detail: string): LaunchExecutableResult => ({ state: 'held', detail })
const ENV_MARKER = '__HARNESS_LAUNCH_ENV__'
export { LAUNCH_LOCATION_VARIABLES } from './nativeLocations.js'
const pickLocations = (environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv => Object.fromEntries(
  LAUNCH_LOCATION_VARIABLES.filter(key => environment[key] !== undefined).map(key => [key, environment[key]]),
)
/**
 * Windows sets no HOME of its own. OpenSSH for Windows does, so the first VM runs (all over SSH) had one; a daemon
 * started any other way (WMI, a scheduled task, the desktop app) held every native launch at "Waiting to read the
 * engine's launch environment" (the Windows VM E2E, 2026-10-15). The profile is the home there, as os.homedir() says.
 */
function withWindowsHome(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
  return process.platform === 'win32' && !environment.HOME ? { ...environment, HOME: homedir() } : environment
}
let probing = 0
const MAX_PROBES = 8
/** How long a captured launch environment answers again. Each capture is a login shell (rc files, then Node),
 *  spawned synchronously from the core: a held launch's pass asked about four times, every pass (measured
 *  2026-10-15). A few seconds joins those; an rc file edited since is read on the next launch after it. */
const ENVIRONMENT_TTL_MS = 10_000
const captured = new Map<string, { at: number; environment: NodeJS.ProcessEnv }>()
const capturing = new Map<string, Promise<NodeJS.ProcessEnv | null>>()

/** Test seam. */
export function clearLaunchEnvironmentCache(): void {
  captured.clear()
  capturing.clear()
}

/** No unavailable or negative shell answer is cached. A slot belongs to the
 * actual child until its callback, including timeout/oversized-output kills.
 * A capture still running is joined; one taken in the last ENVIRONMENT_TTL_MS is answered again. */
export async function launchEnvironment(shell?: string): Promise<NodeJS.ProcessEnv | null> {
  const interactive = interactiveEngineShell(shell)
  if (!interactive) return withWindowsHome(pickLocations(process.env))
  // Keyed by the shell, not its argv: a shell that is not POSIX gets a one-time script file in its argv.
  const key = JSON.stringify([interactive.path, interactive.args, managedNodePath()])
  const hit = captured.get(key)
  if (hit && Date.now() - hit.at < ENVIRONMENT_TTL_MS) return { ...hit.environment }
  const running = capturing.get(key)
  if (running) return running.then(environment => environment && { ...environment })
  if (probing >= MAX_PROBES) return null
  const code = `process.stdout.write(${JSON.stringify(ENV_MARKER)}+JSON.stringify(Object.fromEntries(${JSON.stringify(LAUNCH_LOCATION_VARIABLES)}.filter(k=>process.env[k]!==undefined).map(k=>[k,process.env[k]]))))`
  const argv = engineShellArgv(interactive, [`exec ${shellSingleQuote(managedNodePath())} -e ${shellSingleQuote(code)}`, 'harness-launch-environment'])
  const capture = captureEnvironment(argv).then(environment => {
    capturing.delete(key)
    if (environment) captured.set(key, { at: Date.now(), environment })
    return environment
  })
  capturing.set(key, capture)
  return capture.then(environment => environment && { ...environment })
}

function captureEnvironment(argv: string[]): Promise<NodeJS.ProcessEnv | null> {
  probing++
  return new Promise(done => {
    try {
      const child = probeExecFile(execFile)(argv[0], argv.slice(1), { timeout: 5_000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 }, (error, output) => {
        probing--
        if (error) { done(null); return }
        try {
          const marker = output.lastIndexOf(ENV_MARKER)
          if (marker < 0) { done(null); return }
          const value: unknown = JSON.parse(output.slice(marker + ENV_MARKER.length))
          if (!value || typeof value !== 'object' || Array.isArray(value)
            || Object.values(value).some(item => typeof item !== 'string' || item.includes('\0'))) { done(null); return }
          done(pickLocations(value as NodeJS.ProcessEnv))
        } catch { done(null) }
      })
      child?.stdin?.end()
    } catch { probing--; done(null) }
  })
}

/**
 * The names a launch looks for on PATH, the command first. On Windows `cmd` is never one: it names the command processor
 * (C:\Windows\System32\cmd.exe, ahead of npm's folder on PATH), which every Command Code launch ran instead (F7).
 */
export function launchSearchNames(command: string, recipeNames: readonly string[], platform: NodeJS.Platform = process.platform): string[] {
  return [...new Set([command, ...recipeNames])].filter((name) => platform !== 'win32' || name.toLowerCase() !== 'cmd')
}

/** A complete absence can authorize installation. Unreadable routes and failed
 * shell capture cannot: installing then would risk replacing a working engine. */
export async function captureLaunchExecutable(engine: AgentEngine, shell?: string): Promise<LaunchExecutableResult> {
  const environment = await launchEnvironment(shell)
  if (!environment || !environment.HOME || !isAbsolute(environment.HOME)) return held('Waiting to read the engine’s launch environment.')
  const command = engineBin(engine), override = enginePathOverride(engine)
  // An entry that is not absolute names no fixed folder, so it is left out of the search, as an over-long
  // one is. It is not a reason to hold: `~/.dotnet/tools` is on the login PATH of every Mac with the .NET SDK
  // (its /etc/paths.d file says it that way), and 0.3.74 held every launch on such a computer for good.
  const listed = environment.PATH?.split(delimiter) ?? []
  const entries = listed.filter(path => isAbsolute(path) && path.length <= 4096)
  if (entries.length === 0 || listed.length > 256) return held('Waiting for a bounded, absolute engine search path.')
  const recipe = override ? undefined : engineInstallRecipe(engine)
  const names = launchSearchNames(command, recipe?.executable.names ?? [])
  const candidates = command.includes('/') || isAbsolute(command) ? [resolve(command)] : names.flatMap(name => entries.map(path => join(path, name)))
  if (recipe) candidates.push(...engineInstallPaths(recipe, environment.HOME))
  // The installer also finds an npm engine beside Harness's own Node (its PATH gains that folder, and
  // `npm prefix -g` names it). Looking only here, a Codex in that folder was "missing": every launch dispatched
  // an installer that found it and exited 0 without a word, and the next launch dispatched another (2026-10-19).
  if (recipe?.executable.npmGlobal) candidates.push(...npmRuntimeBins().flatMap(bin => recipe.executable.names.map(name => join(bin, name))))
  // A candidate this account may not reach. Looked past, for a later one it can run; with none, held as before rather
  // than installing over what may be there.
  let unreachable = false
  // A dangling link on the way to a candidate (POSIX): a person's choice, so it never proves the engine absent. Looked
  // past as bash and zsh look past it (ENOENT), for a later candidate it can run; with none, held rather than
  // installing. Held at the
  // link, every start on a Mac with Nix and no profile yet (~/.nix-profile) waited for good, its own Claude Code in
  // ~/.local/bin never reached (2026-10-30).
  let aliased = false
  for (const path of [...new Set(candidates.flatMap(windowsPrograms))]) {
    try {
      const info = statSync(path)
      if (!info.isFile()) return held('Waiting for the selected engine path to name an executable file.')
      accessSync(path, constants.X_OK)
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
        // Windows: statSync follows links, so a PATH entry across a symlink or junction (nvm-windows, Scoop) proves
        // absence like any other. NativePaths refuses links there, which is right for hook files, not for this search.
        // A leaf that exists though statSync cannot follow it is a dangling link: a user's choice, held as on POSIX.
        // Only the leaf is checked: a dangling folder on the way (nvm-windows' nodejs link after its version was
        // removed) still reads as absent here, where POSIX holds on a dangling ancestor.
        // Unlike a POSIX shell, Windows' search stops at the dangling leaf rather than looking past it, so it is
        // still held here, not looked past.
        if (process.platform === 'win32') {
          try { lstatSync(path) } catch (leaf) {
            if ((leaf as NodeJS.ErrnoException).code === 'ENOENT') continue
          }
          return held('Waiting to confirm the engine search path and its aliases.')
        }
        try {
          const paths = new NativePaths(new NativeEvidenceBudget())
          if (paths.resolveSync(path, true)) return held('Waiting for the engine search path to stop changing.')
          // A dangling executable/ancestor alias is an existing user choice,
          // not evidence that installation is safe. Ordinary missing folders
          // and missing descendants of valid aliases still prove absence.
          for (const fact of paths.snapshot()) if (fact.alias) statSync(fact.path)
          paths.verify()
        } catch { aliased = true }
        continue
      }
      // A folder on the search path that this account may not enter, or a file it may not run, hides nothing it could
      // run: every account's PATH has Homebrew's bin (/etc/paths.d/homebrew), and a Harness Team account on a Mac whose
      // Homebrew is its owner's alone (mode 770) held every Claude Code launch here for good, its own Claude Code in
      // ~/.local/bin never reached (2026-10-27).
      const code = (error as NodeJS.ErrnoException).code
      if (code === 'EACCES' || code === 'EPERM') { unreachable = true; continue }
      return held('Waiting to confirm access to the selected engine executable.')
    }
    const executable = executableSnapshot(nativeVersionProbe({ args: [], output: /^$/, timeoutMs: 5_000 }, () => path))
    if (!executable) return held('Waiting for the selected engine executable to stop changing.')
    return { state: 'ready', executable, environment: withNodeForScript(path, environment) }
  }
  if (aliased) return held('Waiting to confirm the engine search path and its aliases.')
  if (unreachable) return held('Waiting to confirm access to the selected engine executable.')
  return recipe ? { state: 'install', recipe, environment: environment as Record<string, string> } : held('Waiting for the configured engine executable to become available.')
}

/**
 * The files a Windows launch can run for [path], in the order CreateProcess and npm's shims make them: its `.exe`, then
 * its `.cmd`, `.bat` or `.com` (an npm shim, run as its script: lib/windows/launch.ts). Not the extensionless sh script
 * npm also writes, which nothing on Windows runs, nor a `.ps1`. Claude Code's native install is `claude.exe` alone, and
 * with only the bare name looked for, every launch of it read as not installed (Windows 11 VM, 2026-10-15). A path
 * that names a program already, and every path elsewhere, is itself.
 */
function windowsPrograms(path: string): string[] {
  if (process.platform !== 'win32' || /\.(?:exe|cmd|bat|com)$/i.test(path)) return [path]
  return ['.exe', '.cmd', '.bat', '.com'].map(extension => path + extension)
}

/**
 * An engine whose executable is a Node script (`#!/usr/bin/env node`: what `npm install -g` leaves for
 * Codex, Claude Code and the other npm engines) needs a `node` on its PATH. Harness installs those with its
 * own Node (lib/engineLaunch.ts `npmRuntimePrelude`; Desktop's setup too, bootstrap/agent_prefetch.dart) and
 * never adds that Node to the person's PATH, so on a computer without a Node of its own the engine could
 * not start: in a fresh Ubuntu VM (2026-10-11) Codex installed by the daemon failed its `--help` probe with
 * "/usr/bin/env: ‘node’: No such file or directory" and every launch of it held for good, and a pane would
 * have failed the same way. Only for such a script, and only when no directory of the launch PATH has a
 * `node`, Harness's Node goes at the END of that PATH. The probe runs with this environment and the pane sets
 * it again after its rc files, so both find the same Node; a Node the person has is never shadowed.
 */
export function withNodeForScript(path: string, environment: NodeJS.ProcessEnv, node: string = managedNodePath()): NodeJS.ProcessEnv {
  const entries = environment.PATH?.split(delimiter) ?? []
  const bin = dirname(node)
  if (!isAbsolute(node) || bin.includes(delimiter) || entries.length >= 256 || !runsOnPathNode(path)) return environment
  const executableFile = (file: string) => { try { accessSync(file, constants.X_OK); return statSync(file).isFile() } catch { return false } }
  if (entries.some(entry => executableFile(join(entry, 'node')))) return environment
  return { ...environment, PATH: [...entries, bin].join(delimiter) }
}

/** The script's first line names `env node` (or `env -S node …`) as its interpreter. */
function runsOnPathNode(path: string): boolean {
  let fd: number | undefined
  try {
    fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK)
    const head = Buffer.alloc(256)
    const line = head.subarray(0, readSync(fd, head, 0, head.length, 0)).toString('utf8').split('\n')[0]!
    return /^#!\s*\S*\/env(?:\s+-S)?\s+node(?:\s|$)/.test(line)
  } catch { return false } finally { if (fd !== undefined) closeSync(fd) }
}