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.

16.3 KB
Raw Blame
/** Recoverable publication of a bounded preparation. Receipts never authorize guessed completion. */
import { randomUUID } from 'node:crypto'
import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, renameSync, writeFileSync } from 'node:fs'
import { basename, dirname, join } from 'node:path'
import { setImmediate as yieldLoop } from 'node:timers/promises'
import { NativeFiles } from '../engines/kit/nativeFiles.js'
import { nativeFileKey, verifyNativePathFacts, type NativePathFact } from '../engines/kit/nativePaths.js'
import { HandoffError, handoffBaseName, handoffExcludeText, handoffHash, handoffIntentHash,
  type HandoffOutcome, type PreparedHandoff } from './handoffAuthority.js'
import { readHandoffFile } from './handoffFiles.js'
import { directorySyncSupported } from './secureState.js'
import { handoffRoute, handoffShape, validateHandoff } from './handoffValidation.js'

const MAX_RECEIPT_BYTES = 20 * 1024 * 1024
const publications = new Map<string, symbol>()
const held = (): never => { throw new HandoffError('HANDOFF_UNAVAILABLE') }
type Stage = { path: string; key: string }
type Receipt = { version: 1; fingerprint: string; prepared: PreparedHandoff;
  outputs: Array<Stage | null>; exclude: Stage | null; destination: NativePathFact[] | null;
  ignore: { key: string; route: NativePathFact[] } | null; committed: boolean }
const missing = (error: unknown): boolean => (error as NodeJS.ErrnoException).code === 'ENOENT'
function exists(path: string): boolean {
  try { lstatSync(path); return true } catch (error) { if (missing(error)) return false; throw error }
}
function sync(path: string, directory = false): void {
  const files = new NativeFiles(), location = files.locate(path)!
  const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW | (directory ? constants.O_DIRECTORY : 0))
  try {
    const info = fstatSync(fd, { bigint: true })
    if (nativeFileKey(info) !== nativeFileKey(location.info)
      || (directory ? !info.isDirectory() : !info.isFile())) return held()
    // A successful disk flush may outlive one inspection budget. Retain the original
    // identity and bound its fresh verification; the request's deadline is never renewed.
    const route = files.paths.snapshot()
    // Windows cannot flush a directory handle (secureState.ts `syncStateDirectory`); NTFS journals the names.
    if (!directory || directorySyncSupported()) fsyncSync(fd)
    verifyNativePathFacts(route)
  } finally { closeSync(fd) }
}
function createFile(path: string, text: string): Stage {
  const route = new NativeFiles(); route.locate(dirname(path))
  const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
  try {
    const opened = fstatSync(fd, { bigint: true })
    const facts = route.paths.snapshot()
    if (!opened.isFile() || opened.nlink !== 1n || nativeFileKey(lstatSync(path, { bigint: true })) !== nativeFileKey(opened)) return held()
    writeFileSync(fd, text); fsyncSync(fd); verifyNativePathFacts(facts)
    if (nativeFileKey(lstatSync(path, { bigint: true })) !== nativeFileKey(opened)) return held()
    return { path, key: nativeFileKey(opened) }
  }
  finally { closeSync(fd) }
}
function directory(path: string): void {
  try { mkdirSync(path, { mode: 0o700 }) } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
  const info = lstatSync(path)
  if (!info.isDirectory() || (info.mode & 0o022) !== 0 || typeof process.getuid === 'function' && info.uid !== process.getuid()) held()
  // Repeat on recovery: an earlier mkdir may have succeeded while its parent fsync failed.
  sync(path, true); sync(dirname(path), true)
}

/** A durable reservation stores the complete redacted preparation before any project write.
 * Stages are recorded only after their exact bytes are durable. An incomplete unrecorded stage is
 * left untouched, and retry creates a fresh one. No existing public file is adopted without proof. */
export async function publishHandoff(directoryPath: string, candidate: PreparedHandoff,
  verify: (prepared: PreparedHandoff, reserved: boolean) => void,
  checkRequest: () => void,
): Promise<HandoffOutcome> {
  const token = Symbol(), locks: string[] = []
  try {
    verify(candidate, false)
    const id = handoffHash(JSON.stringify([candidate.request.agentId, candidate.request.changeId]))
    const keys = [`project:${candidate.project.fileKey}`, `receipt:${directoryPath}/${id}`]
    if (candidate.git.exclude) {
      const parent = new NativeFiles().locate(dirname(candidate.git.exclude))!
      keys.push(`exclude:${nativeFileKey(parent.info)}:${basename(candidate.git.exclude)}`)
    }
    if (keys.some(key => publications.has(key))) throw new HandoffError('BUSY')
    for (const key of keys) { publications.set(key, token); locks.push(key) }
    const fingerprint = handoffIntentHash(candidate)
    directory(dirname(directoryPath)); directory(directoryPath)
    const receiptFolders = new NativeFiles(); directoryPath = receiptFolders.locate(directoryPath)!.path
    const receiptRoute = receiptFolders.paths.snapshot()
    const receiptPath = join(directoryPath, `${id}.json`)
    let previous = readHandoffFile(receiptPath, MAX_RECEIPT_BYTES, true)
    let receipt: Receipt
    if (previous.text !== null) {
      receipt = JSON.parse(previous.text) as Receipt
      if (!handoffShape(receipt, ['version', 'fingerprint', 'prepared', 'outputs', 'exclude', 'destination', 'ignore', 'committed'])) return held()
      validateHandoff(receipt.prepared)
      if (receipt.version !== 1 || typeof receipt.committed !== 'boolean'
        || !Array.isArray(receipt.outputs) || receipt.outputs.length !== 2
        || receipt.fingerprint !== handoffIntentHash(receipt.prepared)
        || !(receipt.destination === null || handoffRoute(receipt.destination))
        || !(receipt.ignore === null || handoffShape(receipt.ignore, ['key', 'route'])
          && typeof receipt.ignore.key === 'string' && receipt.ignore.key.length <= 128 && handoffRoute(receipt.ignore.route))) return held()
      if (receipt.fingerprint !== fingerprint) throw new HandoffError('CHANGE_CONFLICT')
    } else receipt = { version: 1, fingerprint, prepared: candidate, outputs: [null, null],
      exclude: null, destination: null, ignore: null, committed: false }
    const prepared = receipt.prepared
    // A durable private reservation owns the immutable, verified snapshot, even if publication
    // was interrupted before commit. Current native identity remains mandatory on every retry.
    verify(prepared, previous.text !== null)
    const cwd = prepared.project.path, folder = join(cwd, '.harness', 'handoff')
    const base = handoffBaseName(prepared.request.agentId, prepared.request.changeId)
    const outputs = prepared.documents ? [
      { path: join(folder, `${base}.transcript.md`), text: prepared.documents.transcript },
      { path: join(folder, `${base}.md`), text: prepared.documents.markdown },
    ] : []
    const checkStage = (stage: Stage | null, parent: string): void => {
      if (stage !== null && (!handoffShape(stage, ['path', 'key']) || typeof stage.key !== 'string' || stage.key.length > 128
        || typeof stage.path !== 'string' || dirname(stage.path) !== parent
        || !stage.path.startsWith(join(parent, `.${id}.`)) || !stage.path.endsWith('.stage'))) return held()
    }
    receipt.outputs.forEach(stage => checkStage(stage, folder))
    checkStage(receipt.exclude, prepared.exclude ? dirname(prepared.exclude.path) : '')
    if (!prepared.documents && (receipt.outputs.some(Boolean) || receipt.exclude || receipt.destination || receipt.ignore)) return held()
    const receiptFence = (): void => {
      verifyNativePathFacts(receiptRoute)
      const current = readHandoffFile(receiptPath, MAX_RECEIPT_BYTES, true)
      if (current.key !== previous.key || current.version !== previous.version || current.text !== previous.text) return held()
    }
    const save = (): void => {
      receiptFence()
      const text = JSON.stringify(receipt)
      if (Buffer.byteLength(text) > MAX_RECEIPT_BYTES) return held()
      const temporary = createFile(`${receiptPath}.${randomUUID()}.tmp`, text)
      receiptFence()
      checkRequest()
      if (previous.text === null) linkSync(temporary.path, receiptPath)
      else renameSync(temporary.path, receiptPath)
      sync(directoryPath, true)
      previous = readHandoffFile(receiptPath, MAX_RECEIPT_BYTES, true)
      if (previous.key !== temporary.key || previous.text !== text) return held()
    }
    const exclusionBaseline = (): void => {
      if (!prepared.exclude) return
      const exclusion = prepared.exclude, current = readHandoffFile(exclusion.path, 129 * 1024)
      verifyNativePathFacts(exclusion.route.filter(fact => fact.path !== exclusion.path))
      const completed = receipt.exclude && current.key === receipt.exclude.key && current.text === exclusion.after
      if (!completed && (current.text !== exclusion.before || current.version !== exclusion.version)) return held()
    }
    // Before any output is staged, a fresh preparation can preserve the current exclusion as its
    // new effect baseline. A peer may have completed the shared line after our stage was reserved
    // or renamed. Retire only the old receipt pointer; never delete or adopt an old private stage.
    if (previous.text !== null && !receipt.committed && receipt.outputs.every(stage => stage === null)) {
      let baseline = candidate.exclude
      if (prepared.documents && prepared.git.exclude && !baseline) {
        // The current conversation may be empty; its candidate has no writes. The reserved
        // nonempty snapshot still needs the freshly checked exclusion before it can finish.
        const current = readHandoffFile(prepared.git.exclude, 128 * 1024)
        baseline = { path: current.path, before: current.text, after: handoffExcludeText(current.text),
          version: current.version, route: current.route }
      }
      if (JSON.stringify(prepared.exclude) !== JSON.stringify(baseline)) {
        prepared.exclude = baseline
        receipt.exclude = null
        verify(candidate, false); verify(prepared, true); exclusionBaseline(); save()
      }
    }
    if (previous.text === null) {
      if (outputs.some(output => exists(output.path))) return held()
      exclusionBaseline()
      verify(prepared, false)
      if (!prepared.documents) receipt.committed = true
      save()
    }
    const fence = (): void => {
      verify(prepared, true); receiptFence()
      if (receipt.destination) verifyNativePathFacts(receipt.destination)
    }
    const checkpoint = async (): Promise<void> => { await yieldLoop(); fence() }
    await checkpoint()
    if (!prepared.documents) {
      if (!receipt.committed) return held()
      fence(); sync(receiptPath); sync(directoryPath, true); sync(dirname(directoryPath), true); fence()
      checkRequest()
      return prepared.result
    }
    const ignore = join(folder, '.gitignore')
    const confirmIgnore = (): void => {
      if (!receipt.ignore) return held()
      verifyNativePathFacts(receipt.ignore.route)
      const currentIgnore = readHandoffFile(ignore, 64 * 1024, true)
      if (currentIgnore.key !== receipt.ignore.key || currentIgnore.text !== '*\n') return held()
      sync(ignore)
    }
    const guards = (): void => {
      confirmIgnore()
      if (prepared.exclude) {
        const exclusion = prepared.exclude, current = readHandoffFile(exclusion.path, 129 * 1024)
        verifyNativePathFacts(exclusion.route.filter(fact => fact.path !== exclusion.path))
        if (current.text !== exclusion.after) return held()
        if (receipt.exclude) {
          if (current.key !== receipt.exclude.key) return held()
        } else {
          verifyNativePathFacts(exclusion.route)
          if (exclusion.before !== exclusion.after || current.version !== exclusion.version) return held()
        }
        sync(exclusion.path); sync(dirname(exclusion.path), true)
      }
    }
    const confirmed = (): void => outputs.forEach((output, index) => {
      const current = readHandoffFile(output.path, 8 * 1024 * 1024, true)
      if (!receipt.outputs[index] || current.key !== receipt.outputs[index]!.key || current.text !== output.text) return held()
      sync(output.path); sync(folder, true)
    })
    const durable = async (): Promise<void> => {
      fence(); confirmed(); guards()
      await checkpoint()
      sync(join(cwd, '.harness'), true); sync(cwd, true)
      // A rename-visible committed receipt may still have an unconfirmed directory fsync.
      sync(receiptPath); sync(directoryPath, true); sync(dirname(directoryPath), true)
      fence(); guards(); confirmed()
      checkRequest()
    }
    if (receipt.committed) { await durable(); return prepared.result }
    fence()
    exclusionBaseline()
    directory(join(cwd, '.harness')); directory(folder)
    if (!receipt.destination) {
      const folders = new NativeFiles(); folders.locate(folder)
      receipt.destination = folders.paths.snapshot(); save()
    }
    await checkpoint()
    if (!receipt.ignore) {
      if (!exists(ignore)) {
        const staged = createFile(join(folder, `.${id}.${randomUUID()}.stage`), '*\n')
        fence(); checkRequest(); linkSync(staged.path, ignore)
      }
      const observed = readHandoffFile(ignore, 64 * 1024, true)
      if (!observed.key || observed.text !== '*\n') return held()
      receipt.ignore = { key: observed.key, route: observed.route }; save()
    }
    verifyNativePathFacts(receipt.ignore.route)
    const observedIgnore = readHandoffFile(ignore, 64 * 1024, true)
    if (observedIgnore.key !== receipt.ignore.key || observedIgnore.text !== '*\n') return held()
    sync(ignore); sync(folder, true)
    await checkpoint()
    if (prepared.exclude) {
      const exclusion = prepared.exclude, parent = dirname(exclusion.path)
      const excludeFence = (): void => { fence(); verifyNativePathFacts(exclusion.route.filter(fact => fact.path !== exclusion.path)) }
      excludeFence()
      const current = readHandoffFile(exclusion.path, 129 * 1024)
      if (receipt.exclude && current.key === receipt.exclude.key && current.text === exclusion.after) {
        // This transaction completed the rename before a later write/fsync/reply failed.
        sync(exclusion.path); sync(parent, true)
      } else {
        verifyNativePathFacts(exclusion.route)
        if (current.text !== exclusion.before || current.version !== exclusion.version) return held()
        if (exclusion.before !== exclusion.after) {
          if (!receipt.exclude) {
            receipt.exclude = createFile(join(parent, `.${id}.${randomUUID()}.stage`), exclusion.after)
            sync(parent, true); save()
          }
          const staged = readHandoffFile(receipt.exclude.path, 129 * 1024, true)
          if (staged.key !== receipt.exclude.key || staged.text !== exclusion.after) return held()
          excludeFence(); confirmIgnore(); verifyNativePathFacts(exclusion.route)
          const latest = readHandoffFile(exclusion.path, 129 * 1024)
          if (latest.version !== current.version || latest.text !== current.text) return held()
          checkRequest(); renameSync(receipt.exclude.path, exclusion.path); sync(parent, true)
        }
      }
    }
    for (const [index, output] of outputs.entries()) {
      await checkpoint()
      guards()
      if (exists(output.path)) {
        const current = readHandoffFile(output.path, 8 * 1024 * 1024, true)
        if (!receipt.outputs[index] || current.key !== receipt.outputs[index]!.key || current.text !== output.text) return held()
      } else {
        if (!receipt.outputs[index]) {
          receipt.outputs[index] = createFile(join(folder, `.${id}.${randomUUID()}.stage`), output.text)
          sync(folder, true); save()
        }
        const stage = receipt.outputs[index]!, current = readHandoffFile(stage.path, 8 * 1024 * 1024, true)
        if (current.key !== stage.key || current.text !== output.text) return held()
        fence(); guards(); checkRequest(); linkSync(stage.path, output.path); sync(folder, true)
      }
    }
    await checkpoint()
    confirmed(); guards(); fence(); receipt.committed = true; save(); await durable()
    return prepared.result
  } catch (error) {
    if (error instanceof HandoffError) throw error
    if ((error as { code?: string })?.code === 'IDENTITY_UNAVAILABLE') throw new HandoffError('IDENTITY_UNAVAILABLE')
    return held()
  } finally {
    for (const key of locks) if (publications.get(key) === token) publications.delete(key)
  }
}