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.

12.7 KB
Raw Blame
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, symlinkSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, expect, it, vi } from 'vitest'
let root = ''
afterEach(() => { vi.unstubAllEnvs(); vi.resetModules(); if (root) rmSync(root, { recursive: true, force: true }); root = '' })
async function fixture() {
  root = mkdtempSync(join(tmpdir(), 'launch-executable-'))
  const bin = join(root, 'bin'); mkdirSync(bin)
  vi.stubEnv('HOME', root); vi.stubEnv('USERPROFILE', root); vi.stubEnv('PATH', bin); vi.stubEnv('OPENCODE_PATH', '')
  vi.resetModules()
  return { bin, ...await import('./launchExecutable.js') }
}
it('captures an absolute executable once and detects its replacement', async () => {
  const { bin, captureLaunchExecutable } = await fixture()
  // A Windows launch runs a program file, never a bare name (`windowsPrograms`).
  const file = join(bin, process.platform === 'win32' ? 'opencode.exe' : 'opencode'); writeFileSync(file, 'fixture', { mode: 0o700 })
  const result = await captureLaunchExecutable('opencode', '')
  expect(result.state).toBe('ready')
  if (result.state !== 'ready') throw new Error('fixture was held')
  expect(result.executable.command).toBe(file)
  expect(result.executable.current()).toBe(true)
  writeFileSync(file, 'upgraded fixture')
  expect(result.executable.current()).toBe(false)
})
it('distinguishes complete absence from inaccessible or ambiguous candidates', async () => {
  const { bin, captureLaunchExecutable } = await fixture()
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'install' })
  const file = join(bin, 'opencode'); writeFileSync(file, 'fixture'); chmodSync(file, 0o600)
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
  rmSync(file); mkdirSync(file)
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
  vi.stubEnv('PATH', 'relative')
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
})
it('looks past a search-path folder this account may not enter, and still never installs with nothing found after it', async () => {
  // A Harness Team account: Homebrew's bin is on every account's PATH (/etc/paths.d/homebrew), its owner's alone (770).
  // The folder beside Harness's Node is left out: it is the machine's own, and could hold a real engine.
  vi.doMock('../../lib/engineLaunch.js', async (actual) => ({ ...await actual<object>(), npmRuntimeBins: () => [] }))
  const { bin, captureLaunchExecutable } = await fixture()
  vi.doUnmock('../../lib/engineLaunch.js')
  const locked = join(root, 'locked'); mkdirSync(locked); writeFileSync(join(locked, 'opencode'), 'theirs', { mode: 0o700 }); chmodSync(locked, 0o000)
  try {
    vi.stubEnv('PATH', [locked, bin].join(':'))
    // Nothing it can run after it: held, never installed over what the locked folder may hold.
    expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held', detail: 'Waiting to confirm access to the selected engine executable.' })
    const file = join(bin, 'opencode'); writeFileSync(file, 'its own', { mode: 0o700 })
    expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'ready', executable: { command: file } })
  } finally { chmodSync(locked, 0o700) }
})
it('searches the absolute folders of a PATH that also lists what is not one', async () => {
  // The login PATH of a Mac with the .NET SDK: `~/.dotnet/tools`, unexpanded. An empty entry and `.` are as common.
  const { bin, captureLaunchExecutable } = await fixture()
  vi.stubEnv('PATH', ['~/.dotnet/tools', '', '.', 'relative', bin].join(':'))
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'install' })
  const file = join(bin, 'opencode'); writeFileSync(file, 'fixture', { mode: 0o700 })
  const result = await captureLaunchExecutable('opencode', '')
  expect(result).toMatchObject({ state: 'ready', executable: { command: file } })
  // Nothing absolute to search, or more entries than a search is bounded to: still held.
  vi.stubEnv('PATH', '~/.dotnet/tools::.')
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
  vi.stubEnv('PATH', Array(257).fill(bin).join(':'))
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
})
it('never installs over an explicitly configured missing executable', async () => {
  await fixture()
  vi.stubEnv('OPENCODE_PATH', join(root, 'absent'))
  vi.resetModules()
  const { captureLaunchExecutable } = await import('./launchExecutable.js')
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
})

it('holds dangling command aliases instead of authorizing an installation over them', async () => {
  const { bin, captureLaunchExecutable } = await fixture()
  symlinkSync(join(root, 'unavailable-engine'), join(bin, 'opencode'))
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
})
// Nix (Determinate installer) puts ~/.nix-profile/bin on every login PATH, and ~/.nix-profile names a profile that
// is not there until `nix profile install` makes one. Holding at that link, every Claude Code start on such a Mac
// waited for good, its own claude in ~/.local/bin, later on the PATH, never reached (desktop 1.3.42, 2026-10-30).
it('looks past a dangling link on the search path, and still never installs with nothing found after it', async () => {
  vi.doMock('../../lib/engineLaunch.js', async (actual) => ({ ...await actual<object>(), npmRuntimeBins: () => [] }))
  const { bin, captureLaunchExecutable } = await fixture()
  vi.doUnmock('../../lib/engineLaunch.js')
  const profile = join(root, '.nix-profile'); symlinkSync(join(root, 'state', 'nix', 'profiles', 'profile'), profile)
  vi.stubEnv('PATH', [join(profile, 'bin'), bin].join(':'))
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held', detail: expect.stringContaining('aliases') })
  const file = join(bin, 'opencode'); writeFileSync(file, 'its own', { mode: 0o700 })
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'ready', executable: { command: file } })
})
it('looks past a dangling command link to the engine after it, as a shell does', async () => {
  vi.doMock('../../lib/engineLaunch.js', async (actual) => ({ ...await actual<object>(), npmRuntimeBins: () => [] }))
  const { bin, captureLaunchExecutable } = await fixture()
  vi.doUnmock('../../lib/engineLaunch.js')
  const first = join(root, 'first'); mkdirSync(first)
  symlinkSync(join(root, 'removed-engine'), join(first, 'opencode'))
  vi.stubEnv('PATH', [first, bin].join(':'))
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held' })
  const file = join(bin, 'opencode'); writeFileSync(file, 'its own', { mode: 0o700 })
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'ready', executable: { command: file } })
})
it('never looks past a configured engine path that is a dangling link', async () => {
  // The person named this file: there is nothing after it to look for.
  await fixture()
  const link = join(root, 'configured-opencode'); symlinkSync(join(root, 'removed-engine'), link)
  vi.stubEnv('OPENCODE_PATH', link)
  vi.resetModules()
  const { captureLaunchExecutable } = await import('./launchExecutable.js')
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'held', detail: expect.stringContaining('aliases') })
})
it('permits complete absence through a valid search-directory alias', async () => {
  const { bin, captureLaunchExecutable } = await fixture()
  const alias = join(root, 'path-alias'); symlinkSync(bin, alias); vi.stubEnv('PATH', alias)
  expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'install' })
})

it('gives an npm engine Harness\'s Node, after the PATH, when the launch PATH has none', async () => {
  // Codex installed by the daemon with Harness's Node on a computer without one (fresh Ubuntu VM, 2026-10-11):
  // `#!/usr/bin/env node` found no node, so its probe and its pane both failed.
  const { bin, captureLaunchExecutable } = await fixture()
  const { managedNodePath } = await import('../../lib/nodeRuntime.js')
  writeFileSync(join(bin, 'opencode'), '#!/usr/bin/env node\nrequire("./opencode.js")\n', { mode: 0o700 })
  const result = await captureLaunchExecutable('opencode', '')
  expect(result).toMatchObject({ state: 'ready', environment: { PATH: `${bin}:${dirname(managedNodePath())}` } })
})
it('finds an npm engine beside Harness\'s Node, where its installer finds it', async () => {
  // A Codex there was "missing" to the daemon only: each launch dispatched an installer that exited 0 (2026-10-19).
  await fixture()
  const runtime = join(root, 'runtime'), nodeBin = join(runtime, 'node-fixture', 'bin'); mkdirSync(nodeBin, { recursive: true })
  writeFileSync(join(nodeBin, 'node'), '', { mode: 0o700 })
  writeFileSync(join(runtime, 'current-node'), join(nodeBin, 'node'))
  vi.stubEnv('ADAPTER_RUNTIME_DIR', runtime); vi.stubEnv('CODEX_PATH', '')
  vi.resetModules()
  const { captureLaunchExecutable } = await import('./launchExecutable.js')
  expect(await captureLaunchExecutable('codex', '')).toMatchObject({ state: 'install' })
  writeFileSync(join(nodeBin, 'codex'), '#!/usr/bin/env node\n', { mode: 0o700 })
  expect(await captureLaunchExecutable('codex', '')).toMatchObject({ state: 'ready', executable: { command: join(nodeBin, 'codex') } })
})
it('leaves the launch PATH alone for a Node the person has, and for an engine that is not a Node script', async () => {
  const { bin, withNodeForScript } = await fixture()
  const script = join(bin, 'codex'), node = join(root, 'harness-node', 'bin', 'node')
  const environment = { HOME: root, PATH: bin }
  writeFileSync(script, '#!/usr/bin/env -S node --no-warnings\n', { mode: 0o700 })
  expect(withNodeForScript(script, environment, node).PATH).toBe(`${bin}:${dirname(node)}`)
  expect(withNodeForScript(script, environment, 'node')).toBe(environment)
  expect(withNodeForScript(script, { ...environment, PATH: Array(256).fill(bin).join(':') }, node).PATH).toBe(Array(256).fill(bin).join(':'))
  writeFileSync(join(bin, 'node'), '', { mode: 0o700 })
  expect(withNodeForScript(script, environment, node)).toBe(environment)
  rmSync(join(bin, 'node'))
  for (const head of ['#!/bin/sh\nexec node "$0"\n', '#!/usr/bin/env nodejs\n', '\x7fELF']) {
    writeFileSync(script, head)
    expect(withNodeForScript(script, environment, node), head).toBe(environment)
  }
  expect(withNodeForScript(join(root, 'absent'), environment, node)).toBe(environment)
})

// Claude Code's native install on Windows is `claude.exe` alone; npm writes `codex.cmd` beside an extensionless sh
// script nothing on Windows runs. Looked for by the bare name, Claude Code read as not installed (VM, 2026-10-15).
it('finds a Windows engine by its program file, never the sh script npm writes beside it', async () => {
  const { bin, captureLaunchExecutable } = await fixture()
  const platform = Object.getOwnPropertyDescriptor(process, 'platform')!
  Object.defineProperty(process, 'platform', { ...platform, value: 'win32' })
  try {
    writeFileSync(join(bin, 'opencode'), '#!/bin/sh\n', { mode: 0o700 })
    expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'install' })
    writeFileSync(join(bin, 'opencode.cmd'), '@echo off\r\n', { mode: 0o700 })
    expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'ready', executable: { command: join(bin, 'opencode.cmd') } })
    writeFileSync(join(bin, 'opencode.exe'), 'MZ', { mode: 0o700 })
    expect(await captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'ready', executable: { command: join(bin, 'opencode.exe') } })
    // A configured path that names its program, absolute without a slash on Windows (`C:\…\opencode.exe`), is itself.
    vi.stubEnv('OPENCODE_PATH', join(bin, 'opencode.exe'))
    vi.resetModules()
    const again = await import('./launchExecutable.js')
    expect(await again.captureLaunchExecutable('opencode', '')).toMatchObject({ state: 'ready', executable: { command: join(bin, 'opencode.exe') } })
  } finally { Object.defineProperty(process, 'platform', platform) }
})
it('takes the profile as the home on Windows, which sets no HOME of its own', async () => {
  const { launchEnvironment } = await fixture()
  vi.stubEnv('HOME', undefined)
  const platform = Object.getOwnPropertyDescriptor(process, 'platform')!
  try {
    Object.defineProperty(process, 'platform', { ...platform, value: 'win32' })
    const { homedir } = await import('node:os')
    expect((await launchEnvironment())?.HOME).toBe(homedir())
    vi.stubEnv('HOME', root)
    expect((await launchEnvironment())?.HOME).toBe(root)
  } finally {
    Object.defineProperty(process, 'platform', platform)
  }
})