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.

28.4 KB
Raw Blame
import { createHash, randomUUID } from 'node:crypto'
import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { opendir } from 'node:fs/promises'
import { homedir } from 'node:os'
import { dirname, join } from 'node:path'
import { readPrivateStateFile, secureStateDirectory, syncStateDirectory } from './secureState.js'
import type { LaunchModel } from './launchModel.js'

export type AgentCreationOutcome =
  | { state: 'created'; agentId: string; level?: 'native' | 'handoff'; resumed?: boolean
    /** The SSH alias the project's clone got in through (lib/projectFolder.ts `onCloned`). */
    clonedVia?: { alias: string } }
  // `reason`: which check a refusal failed, where its code has several (a resume's RESUME_PREPARATION_FAILED).
  | { state: 'failed'; error: string; detail?: string; reason?: string; preparedFolder?: string; existingFolder?: string
    /** GitHub refused every way this computer had in to the repository. */
    access?: 'denied' }
  | { state: 'unconfirmed' }

export type AgentCreationStatus = AgentCreationOutcome
  | { state: 'pending'; held?: CreationHold }
  | { state: 'missing' | 'cancelled' }

export interface CreationHold { service: string; detail: string }
export interface PendingCreationIntent { id: string; fingerprint: string; request: Record<string, unknown>; held: CreationHold }
export interface CreationAuthority {
  readonly id: string
  /** The original durable intent still owns preparation, or this callback's exact dispatch claim. */
  current(): boolean
  /** Status only; a hold is never permission to repeat an effect. */
  hold(reason: CreationHold): void
}

/** An undispatched request can be recovered. A claimed request cannot: even a
 * dead owner may have left a live child, or changed a project before it died. */
type IntentReceipt = {
  version: 2
  fingerprint: string
  request: Record<string, unknown>
  held: CreationHold
  checksum: string
} | { version: 2; cancelled: true }
type IntentClaim = { fingerprint: string; token: string; kind: 'dispatch' | 'cancel' }
type IntentResult = { fingerprint: string; token: string; outcome: AgentCreationOutcome }

type Receipt = {
  version: 1
  fingerprint: string
  /** The guest a launch was made for. Absent for the owner's, and for every receipt written before guests existed. */
  guest?: string
  outcome: AgentCreationOutcome | { state: 'pending' }
}

function validOutcome(outcome: AgentCreationOutcome | undefined): outcome is AgentCreationOutcome {
  return !!outcome && (outcome.state === 'unconfirmed'
    || (outcome.state === 'failed' && typeof outcome.error === 'string')
    || (outcome.state === 'created' && typeof outcome.agentId === 'string' && !!outcome.agentId
      && (outcome.level === undefined || outcome.level === 'native' || outcome.level === 'handoff')
      && (outcome.resumed === undefined || typeof outcome.resumed === 'boolean')
      && (outcome.clonedVia === undefined || typeof outcome.clonedVia?.alias === 'string')))
}

export class AgentCreationReceiptError extends Error {
  /** `detail`: for a storage failure that is a permissions problem, the folder and what its owner does (task #3861). Never a secret. */
  constructor(readonly code: 'INVALID_CREATION_ID' | 'CREATION_CONFLICT' | 'CREATION_STORAGE_FAILED', readonly detail?: string) {
    super(code)
  }
}

/** A storage failure of the folder [directory]: with the folder and the fix when the account is refused it or does not own it
 *  (stone7890's Mac, 11-06: root-owned, so every start waited for hours on a bare code). Harness never changes a person's folder
 *  permissions: the owner of this computer does, and the words say how. */
function storageFailure(directory: string, error: unknown): AgentCreationReceiptError {
  const { code, message } = error as { code?: string; message?: string }
  const permissions = code === 'EACCES' || code === 'EPERM' || /unsafe owner|writable/.test(message ?? '')
  if (!permissions) return new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
  const home = homedir(), shown = directory === home || directory.startsWith(`${home}/`) ? `~${directory.slice(home.length)}` : directory
  return new AgentCreationReceiptError('CREATION_STORAGE_FAILED',
    `The creation folder ${shown} is not usable by this account (permissions). It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it.`)
}

export function validCreationId(value: unknown): value is string {
  return typeof value === 'string' && /^[a-zA-Z0-9_-]{16,96}$/.test(value)
}

/** Stable semantic identity. Legacy receipts retain only this hash; recoverable
 * model intents also retain their private request, never a resolved credential. */
export function creationFingerprint(value: unknown): string {
  const canonical = (item: unknown): unknown => Array.isArray(item)
    ? item.map(canonical)
    : item && typeof item === 'object'
      ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, child]) => [key, canonical(child)]))
      : item
  return createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')
}

/**
 * Reserve an intent before starting its process. A lost reply, reconnect, or
 * daemon restart never turns that same intent into another process launch.
 *
 * Pending receipts survive crashes. If the daemon stopped between starting a
 * process and saving its result, its outcome is unconfirmed; we never guess
 * that nothing started and run the operation again. Receipts are not evicted by
 * age: even an old retry must not silently become a fresh launch.
 */
export class AgentCreationReceipts {
  private readonly inFlight = new Map<string, { fingerprint: string; result: Promise<AgentCreationStatus> }>()
  // A failed outcome write must not forget an agent we already know was created.
  // The on-disk reservation still prevents a duplicate after a later restart.
  private readonly unsaved = new Map<string, Receipt>()
  private readonly intentResults = new Map<string, IntentResult>()

  constructor(private readonly directory: string) {}

  /** An existing ID is consulted before mutable installation checks. A fresh
   * legacy request still gets its original, correctable validation refusal. */
  has(id: string, fingerprint: string): boolean {
    const receipt = this.read(id)
    if (!receipt) return false
    if (!(receipt.version === 2 && 'cancelled' in receipt) && receipt.fingerprint !== fingerprint) {
      throw new AgentCreationReceiptError('CREATION_CONFLICT')
    }
    return true
  }

  status(id: string): AgentCreationStatus {
    const receipt = this.read(id)
    if (!receipt) return { state: 'missing' }
    if (receipt.version === 2) return this.intentStatus(id, receipt)
    return receipt.outcome.state === 'pending' && !this.inFlight.has(id)
      ? { state: 'unconfirmed' }
      : receipt.outcome
  }

  /** The launch flags kept in a completed native intent, absent for legacy or fallback creates. */
  createdLaunchModel(id: string): LaunchModel | null {
    const receipt = this.read(id)
    if (receipt?.version !== 2 || 'cancelled' in receipt || this.intentStatus(id, receipt).state !== 'created') return null
    const saved = receipt.request
    if (saved.kind !== 'native-create-v1' || !saved.input || typeof saved.input !== 'object') return null
    const launchModel = (saved.input as Record<string, unknown>).launchModel
    if (!launchModel || typeof launchModel !== 'object') return null
    const { model, effort } = launchModel as Record<string, unknown>
    return (model === null || typeof model === 'string') && (effort === null || typeof effort === 'string')
      ? { model, effort } : null
  }

  /** Whose launch an id names: a guest's key, or null for the owner's, an intent's and an unknown id (which a
   * guest hears the same way). */
  creator(id: string): string | null {
    const receipt = this.read(id)
    return receipt?.version === 1 && receipt.guest !== undefined ? receipt.guest : null
  }

  /** `guest` marks a launch made for a guest: it is kept on the receipt so that only that guest, and the owner, can
   * ask what became of it. A guest never attaches to a receipt that is not its own, whatever its fingerprint. */
  run(id: string, fingerprint: string, create: () => Promise<AgentCreationOutcome>, guest?: string): Promise<AgentCreationStatus> {
    const running = this.inFlight.get(id)
    if (running) {
      if (running.fingerprint !== fingerprint) throw new AgentCreationReceiptError('CREATION_CONFLICT')
      return running.result
    }
    const receipt = this.read(id)
    if (receipt) {
      if (guest !== undefined && receipt.version === 2) throw new AgentCreationReceiptError('CREATION_CONFLICT')
      if (receipt.version === 2 && 'cancelled' in receipt) return Promise.resolve(this.intentStatus(id, receipt))
      if (receipt.fingerprint !== fingerprint) throw new AgentCreationReceiptError('CREATION_CONFLICT')
      return Promise.resolve(this.status(id))
    }
    // O_EXCL is also the guard against another daemon reaching the same intent.
    // A partial/corrupt reservation is refused, never treated as a missing one.
    try {
      this.write(id, { version: 1, fingerprint, ...(guest === undefined ? {} : { guest }), outcome: { state: 'pending' } }, true)
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
        const existing = this.read(id)
        if (guest !== undefined && existing?.version === 2) throw new AgentCreationReceiptError('CREATION_CONFLICT')
        if (existing?.version === 2 && 'cancelled' in existing) return Promise.resolve(this.intentStatus(id, existing))
        if (existing?.fingerprint !== fingerprint) throw new AgentCreationReceiptError('CREATION_CONFLICT')
        return Promise.resolve(this.status(id))
      }
      throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    }
    const result = Promise.resolve().then(async (): Promise<AgentCreationStatus> => {
      let outcome: AgentCreationOutcome
      try { outcome = await create() }
      catch { outcome = { state: 'unconfirmed' } }
      const completed: Receipt = { version: 1, fingerprint, ...(guest === undefined ? {} : { guest }), outcome }
      try { this.write(id, completed, false) }
      catch { this.unsaved.set(id, completed) }
      return outcome
    }).finally(() => { this.inFlight.delete(id) })
    this.inFlight.set(id, { fingerprint, result })
    return result
  }

  /** Persist the complete private request before looking up its dependencies.
   * `prepare` may repeat service-owned credential refreshes and independently
   * journalled preparation. It MUST NOT signal or dispatch the agent process.
   * It hands back that effect only when all dependencies are ready. */
  runIntent(id: string, fingerprint: string, request: Record<string, unknown>, held: CreationHold,
    prepare: (request: Record<string, unknown>, authority: CreationAuthority) => Promise<(() => Promise<AgentCreationOutcome>) | null>,
  ): Promise<AgentCreationStatus> {
    const running = this.inFlight.get(id)
    if (running) {
      if (running.fingerprint !== fingerprint) throw new AgentCreationReceiptError('CREATION_CONFLICT')
      return running.result
    }
    let receipt = this.read(id)
    if (!receipt) {
      const intended: IntentReceipt = { version: 2, fingerprint, request: structuredClone(request), held: { ...held },
        checksum: creationFingerprint({ fingerprint, request, held }) }
      this.publish(this.file(id), intended)
      receipt = this.read(id)
    }
    if (!receipt) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    if (receipt.version === 2 && 'cancelled' in receipt) return Promise.resolve(this.intentStatus(id, receipt))
    if (receipt.fingerprint !== fingerprint) throw new AgentCreationReceiptError('CREATION_CONFLICT')
    if (receipt.version === 1) return Promise.resolve(this.status(id))
    const before = this.intentStatus(id, receipt, false)
    if (before.state !== 'pending') return Promise.resolve(before)
    // Decode our own durable bytes, not a caller's later-mutated request object.
    const saved = receipt
    const directory = this.holdDirectory()
    const currentReceipt = (): IntentReceipt => {
      directory.verify()
      const current = this.read(id)
      if (current?.version !== 2 || (!('cancelled' in current) && current.checksum !== saved.checksum)) {
        throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
      }
      return current
    }
    let dispatchToken: string | undefined
    let alive = true
    const authority: CreationAuthority = {
      id,
      current: () => {
        if (!alive) return false
        try {
          if ('cancelled' in currentReceipt()) return false
          const claim = this.claim(id)
          if (!claim) return !dispatchToken && this.intentStatus(id, saved, false).state === 'pending'
          const status = this.intentStatus(id, saved, false)
          return !!dispatchToken && status.state === 'unconfirmed' && !this.intentResults.has(id)
            && !this.readIntentPart(this.intentFile(id, 'result'))
            && claim.kind === 'dispatch' && claim.fingerprint === fingerprint && claim.token === dispatchToken
        } catch { return false }
      },
      hold: reason => {
        if (!authority.current() || dispatchToken) return
        if (!reason.service || reason.service.length > 128 || !reason.detail || reason.detail.length > 2000) return
        // This replaceable sidecar is presentation only. The immutable intent,
        // exclusive claim and exact result remain the entire dispatch authority.
        this.writeHold(id, { checksum: saved.checksum, held: { ...reason } })
      },
    }
    const result = Promise.resolve().then(async (): Promise<AgentCreationStatus> => {
      let effect: (() => Promise<AgentCreationOutcome>) | null
      try { effect = await prepare(saved.request, authority) }
      catch { effect = null }
      const current = this.intentStatus(id, currentReceipt(), false)
      if (!effect || current.state !== 'pending') return current
      const claim: IntentClaim = { fingerprint, token: randomUUID(), kind: 'dispatch' }
      // Exactly the successful publisher executes. In particular, seeing our
      // own claim after a failed directory fsync never grants a second attempt.
      if (!this.publish(this.intentFile(id, 'claim'), claim, true)) return this.intentStatus(id, saved, false)
      dispatchToken = claim.token
      // A directory or primary intent replaced during service preparation must
      // not inherit this callback's authority, even if a later cancel created a
      // fresh tombstone at the same pathname. The open descriptor pins identity.
      if ('cancelled' in currentReceipt() || this.claim(id)?.token !== claim.token) {
        throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
      }
      let outcome: AgentCreationOutcome
      try { outcome = await effect() } catch { outcome = { state: 'unconfirmed' } }
      const completed: IntentResult = { fingerprint, token: claim.token, outcome }
      let published = false
      try { published = this.publish(this.intentFile(id, 'result'), completed, true) } catch { /* Retain the known outcome under its exact claim. */ }
      if (!published) {
        this.intentResults.set(id, completed)
        // EEXIST or a failed save is not permission to hide conflicting disk
        // evidence beneath a memory-only success.
        return this.intentStatus(id, currentReceipt(), false)
      }
      return outcome
    }).finally(() => { alive = false; directory.close(); clearTimeout(replyTimer); this.inFlight.delete(id) })
    // The client gets its held receipt promptly while the SAME preparation
    // continues. A slow successful service answer can still win dispatch;
    // reconnects must not start several preparations for that one request.
    let replyTimer: ReturnType<typeof setTimeout>
    const answer = new Promise<AgentCreationStatus>((resolve, reject) => {
      replyTimer = setTimeout(() => {
        try { resolve(this.intentStatus(id, saved)) } catch (error) { reject(error) }
      }, 5_000)
      replyTimer.unref?.()
      void result.then(resolve, reject)
    })
    this.inFlight.set(id, { fingerprint, result: answer })
    return answer
  }

  /** Cancellation shares dispatch's exclusive slot. A missing ID gets a durable
   * tombstone too: a delayed create cannot undo an acknowledged cancellation. */
  cancelIntent(id: string): AgentCreationStatus {
    let receipt = this.read(id)
    if (!receipt) {
      this.publish(this.file(id), { version: 2, cancelled: true })
      receipt = this.read(id)
    }
    if (!receipt) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    if (receipt.version === 1) return this.status(id)
    if ('cancelled' in receipt) { this.ensureDirectory(); this.syncDirectory(); return this.intentStatus(id, receipt) }
    // Incomplete evidence cannot be repaired into an acknowledged cancellation.
    this.intentStatus(id, receipt, false)
    this.publish(this.intentFile(id, 'claim'), { fingerprint: receipt.fingerprint, token: randomUUID(), kind: 'cancel' }, true)
    const status = this.intentStatus(id, receipt, false)
    if (status.state === 'cancelled') this.syncDirectory()
    return status
  }

  /** Streaming recovery never loads an unbounded directory into the core. Old
   * receipts and terminal tombstones stay authoritative, but are not scheduled. */
  pendingIntent(id: string): PendingCreationIntent | null {
    const receipt = this.read(id)
    if (receipt?.version !== 2 || 'cancelled' in receipt || this.intentStatus(id, receipt, false).state !== 'pending') return null
    return { id, fingerprint: receipt.fingerprint, request: receipt.request, held: receipt.held }
  }

  async *pendingIntents(): AsyncGenerator<PendingCreationIntent | null> {
    this.ensureDirectory()
    const entries = await opendir(this.directory)
    for await (const entry of entries) {
      if (!entry.isFile() || !entry.name.endsWith('.json')) { yield null; continue }
      const id = entry.name.slice(0, -5)
      if (!validCreationId(id)) { yield null; continue }
      try {
        yield this.pendingIntent(id)
      } catch { yield null /* Corrupt evidence remains held; one bad ID cannot block its siblings. */ }
    }
  }

  private intentFile(id: string, part: 'claim' | 'result'): string { return `${this.file(id)}.${part}` }

  private readIntentPart<T>(file: string): T | null {
    try {
      const value: unknown = JSON.parse(readPrivateStateFile(file, 262_144))
      if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid receipt part')
      return value as T
    }
    catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
      throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    }
  }

  private claim(id: string): IntentClaim | null {
    const claim = this.readIntentPart<IntentClaim>(this.intentFile(id, 'claim'))
    if (claim && (!/^[a-f0-9]{64}$/.test(claim.fingerprint) || typeof claim.token !== 'string' || !claim.token
      || (claim.kind !== 'dispatch' && claim.kind !== 'cancel'))) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    return claim
  }

  private intentStatus(id: string, receipt: IntentReceipt, live = this.inFlight.has(id)): AgentCreationStatus {
    const known = this.intentResults.get(id)
    if ('cancelled' in receipt) {
      if (known || this.claim(id) || this.readIntentPart(this.intentFile(id, 'result'))) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
      return { state: 'cancelled' }
    }
    const claim = this.claim(id)
    const result = this.readIntentPart<IntentResult>(this.intentFile(id, 'result'))
    // A completed effect cannot become pending or cancelled when its disk
    // evidence disappears. Its retained result still requires the exact claim.
    if (known && (!claim || claim.kind !== 'dispatch' || known.fingerprint !== claim.fingerprint || known.token !== claim.token)) {
      throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    }
    if (!claim) {
      if (result) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
      return { state: 'pending', held: this.readHold(id, receipt) }
    }
    if (claim.fingerprint !== receipt.fingerprint) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    if (claim.kind === 'cancel') {
      if (result) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
      return { state: 'cancelled' }
    }
    if (result) {
      if (result.fingerprint !== claim.fingerprint || result.token !== claim.token || !validOutcome(result.outcome)
        || (known && creationFingerprint(known.outcome) !== creationFingerprint(result.outcome))) {
        throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
      }
      return result.outcome
    }
    if (known) return known.outcome
    return { state: live ? 'pending' : 'unconfirmed' }
  }

  private publish(file: string, value: unknown, existingDirectory = false): boolean {
    const bytes = JSON.stringify(value)
    if (Buffer.byteLength(bytes) > 262_144) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    const temporary = `${file}.${randomUUID()}.tmp`
    let opened = false
    try {
      if (existingDirectory) secureStateDirectory(this.directory, false)
      this.ensureDirectory()
      const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
      opened = true
      try { writeFileSync(fd, bytes); fsyncSync(fd) } finally { closeSync(fd) }
      try { linkSync(temporary, file) }
      catch (error) {
        if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
        throw error
      }
      this.syncDirectory()
      return true
    } catch (error) { throw error instanceof AgentCreationReceiptError ? error : storageFailure(this.directory, error) }
    finally { if (opened) rmSync(temporary, { force: true }) }
  }

  private readHold(id: string, receipt: Extract<IntentReceipt, { checksum: string }>): CreationHold {
    try {
      const value = JSON.parse(readPrivateStateFile(join(this.directory, `${id}.hold`), 16_384))
      if (value.checksum === receipt.checksum && typeof value.held?.service === 'string' && value.held.service.length <= 128
        && typeof value.held.detail === 'string' && value.held.detail.length <= 2000) return value.held
    } catch { /* Missing or damaged status cannot grant or revoke dispatch. */ }
    return receipt.held
  }

  private writeHold(id: string, value: { checksum: string; held: CreationHold }): void {
    const target = join(this.directory, `${id}.hold`), temporary = `${target}.${randomUUID()}.tmp`
    let fd: number | undefined
    try {
      secureStateDirectory(this.directory, false)
      fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
      writeFileSync(fd, JSON.stringify(value)); fsyncSync(fd)
      renameSync(temporary, target); this.syncDirectory()
    } finally {
      if (fd !== undefined) { closeSync(fd); rmSync(temporary, { force: true }) }
    }
  }

  private syncDirectory(path = this.directory, ancestor = false): void {
    syncStateDirectory(path, constants.O_RDONLY | constants.O_DIRECTORY | (ancestor ? 0 : constants.O_NOFOLLOW))
  }

  private holdDirectory(): { verify(): void; close(): void } {
    let fd: number | undefined
    try {
      fd = openSync(this.directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
      const identity = fstatSync(fd)
      return {
        verify: () => {
          try {
            const current = lstatSync(this.directory)
            if (!current.isDirectory() || current.dev !== identity.dev || current.ino !== identity.ino) throw new Error('Replaced receipt directory')
          } catch { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') }
        },
        close: () => closeSync(fd!),
      }
    } catch {
      if (fd !== undefined) closeSync(fd)
      throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    }
  }

  /** Publish every new directory name before using a child beneath it, in the
   * same order as engine-home adoption. Ancestors are flushed, never chmodded. */
  private ensureDirectory(path = this.directory, depth = 0): void {
    if (depth > 32) throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
    try {
      if (path === this.directory) secureStateDirectory(path, false)
      else if (!statSync(path).isDirectory()) throw new Error('Not a directory')
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
      this.ensureDirectory(dirname(path), depth + 1)
      try { mkdirSync(path, { mode: 0o700 }) }
      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
      if (path === this.directory) secureStateDirectory(path, false)
    }
    this.syncDirectory(dirname(path), true)
  }

  private file(id: string): string {
    if (!validCreationId(id)) throw new AgentCreationReceiptError('INVALID_CREATION_ID')
    return join(this.directory, `${id}.json`)
  }

  private read(id: string): Receipt | IntentReceipt | null {
    const file = this.file(id)
    const unsaved = this.unsaved.get(id)
    if (unsaved) return unsaved
    const completedIntent = this.intentResults.has(id)
    try { secureStateDirectory(this.directory, false) }
    catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !completedIntent) return null
      throw storageFailure(this.directory, error)
    }
    try {
      const value = JSON.parse(readPrivateStateFile(file, 262_144)) as Partial<Receipt> | Partial<IntentReceipt>
      if (value.version === 2) {
        if ('cancelled' in value && value.cancelled === true && Object.keys(value).sort().join(',') === 'cancelled,version') return { version: 2, cancelled: true }
        if ('request' in value && value.request && typeof value.request === 'object' && !Array.isArray(value.request)
          && /^[a-f0-9]{64}$/.test(value.fingerprint ?? '') && value.held && typeof value.held.service === 'string'
          && typeof value.held.detail === 'string'
          && value.checksum === creationFingerprint({ fingerprint: value.fingerprint, request: value.request, held: value.held })) return value as IntentReceipt
        throw new Error('Invalid creation intent')
      }
      const outcome = value.version === 1 ? value.outcome : undefined
      if (completedIntent || this.readIntentPart(this.intentFile(id, 'claim')) || this.readIntentPart(this.intentFile(id, 'result'))) {
        throw new Error('Legacy receipt has conflicting intent evidence')
      }
      if (value.version !== 1 || !/^[a-f0-9]{64}$/.test(value.fingerprint ?? '') || !outcome
          || (value.guest !== undefined && (typeof value.guest !== 'string' || !value.guest)) ||
          !['pending', 'unconfirmed', 'created', 'failed'].includes(outcome.state) ||
          (outcome.state === 'created' && (typeof outcome.agentId !== 'string' || !outcome.agentId ||
            (outcome.level !== undefined && outcome.level !== 'native' && outcome.level !== 'handoff') ||
            (outcome.resumed !== undefined && typeof outcome.resumed !== 'boolean'))) ||
          (outcome.state === 'failed' && typeof outcome.error !== 'string')) {
        throw new Error('Invalid creation receipt')
      }
      return value as Receipt
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !completedIntent
        && !this.readIntentPart(this.intentFile(id, 'claim')) && !this.readIntentPart(this.intentFile(id, 'result'))) return null
      throw storageFailure(this.directory, error)
    }
  }

  private write(id: string, receipt: Receipt, exclusive: boolean): void {
    if (exclusive) this.ensureDirectory()
    else secureStateDirectory(this.directory, false)
    const file = this.file(id)
    const writing = exclusive ? file : `${file}.${process.pid}.${randomUUID()}.tmp`
    let opened = false
    try {
      const fd = openSync(writing, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
      opened = true
      try { writeFileSync(fd, JSON.stringify(receipt)); fsyncSync(fd) }
      finally { closeSync(fd) }
      if (!exclusive) renameSync(writing, file)
      syncStateDirectory(dirname(file), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
    } finally {
      // Failed reservations stay on disk so a partial write cannot permit a
      // duplicate. Only this write's private replacement file is disposable.
      if (!exclusive && opened) rmSync(writing, { force: true })
    }
  }
}