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.

17.0 KB
Raw Blame
/**
 * Putting a prepared PTY payload (ptyPayload.ts) in use, and taking it back out (spec §3, "How a payload is
 * installed" and "Rollback"). The layout is installLayout.ts's:
 *
 *   <root>\bin\harness.exe, harness-launch.exe     copies out of the version folder in use
 *   <root>\runtime\pty\<version>\                  the six payload files, never replaced once complete
 *   <root>\runtime\pty\current-pty                 the version in use (ptyHost/launch.ts currentPtyVersion)
 *   <root>\runtime\pty\pty-pending.json            { version, previous } while the new version is on probation
 *   <root>\runtime\pty\pty-rejected.json           versions rolled back on this machine, never tried again
 *
 * Windows cannot overwrite or delete a running .exe, but it can rename one. So a bin file is never written in place:
 * the old one is kept aside as `<name>.old-<pid>-<ms>` and the new one is renamed in (putInPlace); the aside files
 * are swept once nothing runs them. Nothing here calls a Windows API, so it is tested on every OS.
 */
import { copyFileSync, existsSync, linkSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { basename, dirname, join } from 'node:path'
import { VERSION_DIR } from '../ptyHost/launch.js'
import { isSingleSegment, readPointer, writePointer } from './installLayout.js'
import { PTY_PAYLOAD_FILES, PtyPayloadRefused, type PreparedPty } from './ptyPayload.js'

export const PTY_POINTER = 'current-pty'
export const PTY_PENDING = 'pty-pending.json'
export const PTY_REJECTED = 'pty-rejected.json'
/** The bin files that come out of the payload, in the order they are replaced. */
export const BIN_FILES = ['harness.exe', 'harness-launch.exe'] as const
/** What a sweep of bin\ removes: our aside files and install.ps1's (`.<name>.old-*`), our temporary copies, and the
 *  `<name>~RF<hex>.TMP` backups that File.Replace leaves when install.ps1 replaces a running program. */
const SWEPT = [/\.old-/, /^\..+\.new-\d+-\d+$/, /~RF.*\.TMP$/i]

/** The calls that change files, so the tests can make any one of them fail. */
export interface PtyInstallFs {
  rename: (from: string, to: string) => void
  link: (existing: string, newPath: string) => void
  copyFile: (from: string, to: string) => void
  writeFile: (path: string, data: string) => void
  rm: (path: string, options?: { recursive?: boolean; force?: boolean }) => void
  sleep: (ms: number) => void
}

export const defaultPtyInstallFs: PtyInstallFs = {
  rename: renameSync,
  link: linkSync,
  copyFile: copyFileSync,
  writeFile: writeFileSync,
  rm: rmSync,
  // Synchronous on purpose, as in installLayout.ts: the caller holds the spawn lock and is synchronous.
  sleep: (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) },
}

/**
 * The codes Windows gives while a file is held: by an antivirus scan or the indexer for a moment, or, for a rename
 * over a program, for as long as it runs. Waiting can fix those, and nothing else.
 */
const RETRIED = new Set(['EPERM', 'EBUSY', 'EACCES'])
const ATTEMPTS = 5
const codeOf = (error: unknown) => (error as NodeJS.ErrnoException)?.code ?? ''
const backoff = (attempt: number) => 25 * 2 ** (attempt - 1)

function renameRetrying(fs: PtyInstallFs, from: string, to: string): void {
  for (let attempt = 1; ; attempt++) {
    try {
      fs.rename(from, to)
      return
    } catch (error) {
      if (!RETRIED.has(codeOf(error)) || attempt >= ATTEMPTS) throw error
      fs.sleep(backoff(attempt))
    }
  }
}

function tryRm(fs: PtyInstallFs, path: string, options: { recursive?: boolean; force?: boolean } = { force: true }): void {
  try { fs.rm(path, options) } catch { /* a running file on Windows: swept later */ }
}

const ptyRootOf = (rootDir: string) => join(rootDir, 'runtime', 'pty')

/** `<dir>\<stem>-<pid>-<ms>`, not taken yet: two replacements of one file within a millisecond must not meet. */
function freshName(dir: string, stem: string): string {
  for (let ms = Date.now(); ; ms++) {
    const candidate = join(dir, `${stem}-${process.pid}-${ms}`)
    if (!existsSync(candidate)) return candidate
  }
}

/** What [putInPlace] did, so it can be undone: where the old file went (null when there was none). */
interface Replaced { target: string; aside: string | null }

/**
 * After a failed rename-in, the old file goes straight back. Any error is retried here (bounded): a target left
 * missing while its bytes sit under an `.old-` name is the one outcome that is not allowed.
 */
function putBack(fs: PtyInstallFs, aside: string, target: string): void {
  for (let attempt = 1; ; attempt++) {
    try {
      fs.rename(aside, target)
      return
    } catch (error) {
      if (attempt >= ATTEMPTS) throw error
      fs.sleep(backoff(attempt))
    }
  }
}

/**
 * Rename the old [target] aside and [ready] in, as one unit: nothing runs between the two renames, so the path is
 * missing only for that moment. A failed rename-in puts the old file back at once; any wait happens with it in
 * place, and then the pair is tried again. The entry is in [done] across the gap, so if even the put-back fails,
 * the caller's undo still knows where the old file is.
 */
function swapPair(fs: PtyInstallFs, ready: string, target: string, aside: string, done: Replaced[]): void {
  for (let attempt = 1; ; attempt++) {
    try {
      fs.rename(target, aside)
    } catch (error) {
      if (!RETRIED.has(codeOf(error)) || attempt >= ATTEMPTS) throw error
      fs.sleep(backoff(attempt))
      continue
    }
    const entry: Replaced = { target, aside }
    done.push(entry)
    try {
      fs.rename(ready, target)
      return
    } catch (error) {
      try {
        putBack(fs, aside, target)
      } catch (putBackError) {
        // The put-back failure is what is thrown; the rename-in failure that led to it stays readable.
        throw Object.assign(putBackError as Error, { cause: error })
      }
      done.splice(done.indexOf(entry), 1)
      if (!RETRIED.has(codeOf(error)) || attempt >= ATTEMPTS) throw error
      fs.sleep(backoff(attempt))
    }
  }
}

/**
 * Put [ready] (a file already in bin\) at `<bin>\<name>`. When there is no old file, a plain rename. Otherwise one
 * rename over the old file first, which keeps the path answering throughout; with [keepOld] the old file first gets
 * a second name (a hard link, the aside file the undo needs). Windows refuses that rename while the old file runs,
 * and a link fails on FAT or for a running image: then [swapPair].
 */
function putInPlace(fs: PtyInstallFs, ready: string, bin: string, name: string, done: Replaced[], keepOld: boolean): void {
  const target = join(bin, name)
  if (!existsSync(target)) {
    renameRetrying(fs, ready, target)
    done.push({ target, aside: null })
    return
  }
  if (keepOld) {
    const link = freshName(bin, `${name}.old`)
    let linked = false
    try {
      fs.link(target, link)
      linked = true
    } catch { /* no second name here; the pair keeps the old file instead */ }
    if (linked) {
      try {
        fs.rename(ready, target)
        done.push({ target, aside: link })
        return
      } catch (error) {
        tryRm(fs, link)
        if (!RETRIED.has(codeOf(error))) throw error
      }
    }
  } else {
    try {
      fs.rename(ready, target)
      return
    } catch (error) {
      if (!RETRIED.has(codeOf(error))) throw error
    }
  }
  swapPair(fs, ready, target, freshName(bin, `${name}.old`), done)
}

/** Copy [source] to a temporary name in bin\ (before any rename touches the path), then [putInPlace]. */
function replaceBinFile(fs: PtyInstallFs, source: string, bin: string, name: string, done: Replaced[]): void {
  const temporary = freshName(bin, `.${name}.new`)
  try {
    fs.copyFile(source, temporary)
    putInPlace(fs, temporary, bin, name, done, true)
  } finally {
    tryRm(fs, temporary)
  }
}

/** Undo one [putInPlace]: the old file goes back the same way the new one came in, since the new one may run now. */
function undoReplaced(fs: PtyInstallFs, { target, aside }: Replaced): void {
  const bin = dirname(target)
  if (aside) return putInPlace(fs, aside, bin, basename(target), [], false)
  try {
    fs.rm(target, { force: true })
  } catch {
    // A new file someone already runs cannot be deleted on Windows; moved aside, it is swept later.
    fs.rename(target, freshName(bin, `${basename(target)}.old`))
  }
}

/** Write [path] whole or not at all: a reader never sees half a marker. */
function writeJson(fs: PtyInstallFs, path: string, value: unknown): void {
  const temporary = freshName(dirname(path), `.${basename(path)}.tmp`)
  try {
    fs.writeFile(temporary, JSON.stringify(value))
    renameRetrying(fs, temporary, path)
  } finally {
    tryRm(fs, temporary)
  }
}

function sameFiles(a: string, b: string): boolean {
  return PTY_PAYLOAD_FILES.every((name) => {
    try {
      return readFileSync(join(a, name)).equals(readFileSync(join(b, name)))
    } catch {
      return false
    }
  })
}

/** Run every undo step, even after one fails: each one left undone is a file out of place. */
function undoAll(steps: Array<() => void>): void {
  for (const step of [...steps].reverse()) {
    try { step() } catch { /* best effort; the original failure is what the caller hears */ }
  }
}

/**
 * Put [prepared] in use. The caller holds the daemon spawn lock. In order: the staging folder becomes
 * `<runtime>\pty\<version>\`; `bin\harness.exe` then `bin\harness-launch.exe` are replaced; `pty-pending.json`
 * records `{ version, previous }`; `current-pty` names the new version. A failure at any step undoes the steps
 * before it (the old bin files go back, the marker goes, the pointer is never moved) and is rethrown as it was.
 * Only content is refused ([PtyPayloadRefused]): a version launch.ts cannot read, or an existing version folder
 * with other files. Returns false, having done nothing, when `current-pty` already names the version (another
 * installer got there first). The staging folder is gone afterwards, whatever happened.
 */
export function installPreparedPty(prepared: PreparedPty, rootDir: string, fs: PtyInstallFs = defaultPtyInstallFs): boolean {
  const ptyRoot = ptyRootOf(rootDir)
  const bin = join(rootDir, 'bin')
  const { version, staging } = prepared
  const versionDir = join(ptyRoot, version)
  const undo: Array<() => void> = []
  try {
    if (!VERSION_DIR.test(version)) throw new PtyPayloadRefused(`version ${JSON.stringify(version)} is not a version folder name`)
    // A version still on probation must be confirmed or rolled back first: its marker names the one to go back to.
    if (existsSync(join(ptyRoot, PTY_PENDING))) throw new Error(`a pty version is still on probation (${PTY_PENDING})`)
    // Without a version to go back to, probation could not roll the new one back.
    const previous = readPointer(ptyRoot, PTY_POINTER)
    if (previous === null) throw new Error('no installed pty version to roll back to')
    if (previous === version) return false

    // 1. The version folder. A complete one is never replaced: a host may run from it.
    if (existsSync(versionDir)) {
      if (!sameFiles(versionDir, staging)) throw new PtyPayloadRefused(`${versionDir} exists with other files`)
    } else {
      renameRetrying(fs, staging, versionDir)
      // Back to the staging name first, so a folder that half fails to delete is never taken for a complete one.
      undo.push(() => { fs.rename(versionDir, staging) })
    }

    // 2. The bin files.
    const replaced: Replaced[] = []
    undo.push(() => { undoAll(replaced.map((entry) => () => undoReplaced(fs, entry))) })
    for (const name of BIN_FILES) replaceBinFile(fs, join(versionDir, name), bin, name, replaced)

    // 3. The probation marker.
    const marker = join(ptyRoot, PTY_PENDING)
    undo.push(() => { fs.rm(marker, { force: true }) })
    writeJson(fs, marker, { version, previous })

    // 4. The pointer, last: it is what makes the version the one in use.
    writePointer(ptyRoot, PTY_POINTER, version, { rename: fs.rename, sleep: fs.sleep })
    return true
  } catch (error) {
    undoAll(undo)
    throw error
  } finally {
    // A just-run canary can hold a file for a moment; a failed delete must not replace the real outcome.
    tryRm(fs, staging, { recursive: true, force: true })
  }
}

export interface PtyPending { version: string; previous: string }
type Pending = PtyPending

/** The version on probation and the one it replaced, or null when none is (or its marker cannot be read). */
export function readPtyPending(rootDir: string): PtyPending | null {
  return readPending(ptyRootOf(rootDir))
}

function readPending(ptyRoot: string): Pending | null {
  try {
    const value = JSON.parse(readFileSync(join(ptyRoot, PTY_PENDING), 'utf8')) as Partial<Pending>
    if (typeof value?.version !== 'string' || !isSingleSegment(value.version)) return null
    if (typeof value.previous !== 'string' || !isSingleSegment(value.previous)) return null
    return { version: value.version, previous: value.previous }
  } catch {
    return null
  }
}

export interface PtyRestore {
  /** There was a version on probation, and it is now rejected and its marker gone. */
  found: boolean
  /** `current-pty` names the previous version again. */
  pointer: boolean
  /** The bin files copied back from the previous version. */
  restored: string[]
  /** The bin files left as they were: missing from the previous version, or a copy back that failed and was undone. */
  kept: string[]
  /** The bin files whose copy back failed and whose undo failed too: the path is missing, and its last bytes sit in
   *  a `bin\<name>.old-*` file. The caller must put one back before a sweep. */
  missing: string[]
}

/**
 * Roll a version on probation back. The rejection is recorded first. `current-pty` names `previous` again when its
 * host is still there, and each bin file `previous` still has is copied back the rename-aside way; a missing one
 * keeps the current file. The version folder stays; a host may still run from it (spec §3 removes it later). Only a
 * failed pointer or record write throws, and a retry repeats nothing that took: a restore never sticks on a
 * version folder that is gone or incomplete.
 */
export function restorePty(rootDir: string, fs: PtyInstallFs = defaultPtyInstallFs): PtyRestore {
  const ptyRoot = ptyRootOf(rootDir)
  const result: PtyRestore = { found: false, pointer: false, restored: [], kept: [], missing: [] }
  const pending = readPending(ptyRoot)
  if (!pending) return result
  const previousDir = join(ptyRoot, pending.previous)
  const has = (name: string) => existsSync(join(previousDir, name))

  const rejected = rejectedPtyVersions(rootDir)
  if (!rejected.includes(pending.version)) writeJson(fs, join(ptyRoot, PTY_REJECTED), [...rejected, pending.version])

  if (has('harness-pty.exe')) {
    writePointer(ptyRoot, PTY_POINTER, pending.previous, { rename: fs.rename, sleep: fs.sleep })
    result.pointer = true
  }
  const bin = join(rootDir, 'bin')
  for (const name of BIN_FILES) {
    if (!has(name)) { result.kept.push(name); continue }
    const done: Replaced[] = []
    try {
      replaceBinFile(fs, join(previousDir, name), bin, name, done)
      result.restored.push(name)
    } catch {
      // Swallowed so a restore never sticks, but only once the current file is back where it was, if it can be.
      undoAll(done.map((entry) => () => undoReplaced(fs, entry)))
      ;(existsSync(join(bin, name)) ? result.kept : result.missing).push(name)
    }
  }
  fs.rm(join(ptyRoot, PTY_PENDING), { force: true })
  result.found = true
  return result
}

/** The version on probation came back healthy: it stays. */
export function confirmPty(rootDir: string, fs: PtyInstallFs = defaultPtyInstallFs): void {
  fs.rm(join(ptyRootOf(rootDir), PTY_PENDING), { force: true })
}

/** The versions rolled back on this machine. A missing or unreadable list is empty. */
export function rejectedPtyVersions(rootDir: string): string[] {
  try {
    const value: unknown = JSON.parse(readFileSync(join(ptyRootOf(rootDir), PTY_REJECTED), 'utf8'))
    return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []
  } catch {
    return []
  }
}

/**
 * Delete the leftovers in bin\: `*.old-*` aside files (ours and install.ps1's `.<name>.old-*`), `.<name>.new-*`
 * temporary copies of an interrupted install, and install.ps1's `*~RF*.TMP`. One that is still running cannot be
 * deleted on Windows and is left for the next sweep. Returns how many are left. The caller holds the daemon spawn
 * lock: an install's `.new-*` copy and, mid-pair, its `.old-*` aside file are the only copies of their bytes, so a
 * sweep outside the lock can break a concurrent install or lose a path while it is renamed aside.
 */
export function sweepAsideFiles(rootDir: string, fs: PtyInstallFs = defaultPtyInstallFs): number {
  const bin = join(rootDir, 'bin')
  let names: string[]
  try {
    names = readdirSync(bin)
  } catch {
    return 0
  }
  let left = 0
  for (const name of names.filter((n) => SWEPT.some((pattern) => pattern.test(n)))) {
    try {
      fs.rm(join(bin, name))
    } catch (error) {
      // Gone already (another sweep) is as good as deleted.
      if (codeOf(error) !== 'ENOENT') left++
    }
  }
  return left
}