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.9 KB
Raw Blame
/** Stopped work is durable history, separate from the registry of live terminal routes. */
import { closeSync, constants, fsyncSync, lstatSync, openSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, type BigIntStats } from 'node:fs'
import { randomUUID } from 'node:crypto'
import { dirname, join } from 'node:path'
import { env } from '../config/env.js'
import { isTerminalEngine } from '../engines/types.js'
import { atomicWriteJson, projectDisplayName, strictPersistedRow, type RegisteredSession } from './registry.js'
import { readPrivateStateFile, secureStateDirectory, syncStateDirectory } from './secureState.js'
import { sameProcessIdentity } from './terminalRuntime.js'
import { conversationKey } from './conversationIdentity.js'

const SAFE_ID = /^[a-zA-Z0-9_-]{1,128}$/
const CATALOG_CACHE_RECORDS = 2048
const CATALOG_CACHE_BYTES = 4 * 1024 * 1024
const CATALOG_CACHE_MS = 30_000

function catalogFingerprint(stat: BigIntStats): string {
  // ctime catches in-place edits even if a writer restores mtime. Inode/device
  // distinguish atomic replacements; mode/owner/type changes must miss too.
  return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.birthtimeNs,
    stat.mode, stat.uid, stat.gid, stat.nlink].join(':')
}

export class StoppedAgentStore {
  private readonly catalogCache = new Map<string, { fingerprint: string; bytes: number; at: number; session: RegisteredSession }>()
  private catalogCacheBytes = 0

  constructor(private readonly directory = join(env.ADAPTER_DATA_DIR, 'stopped-agents')) {}

  get(agentId: string): RegisteredSession | null {
    if (!SAFE_ID.test(agentId)) return null
    try {
      secureStateDirectory(this.directory, false)
      const raw = JSON.parse(readPrivateStateFile(join(this.directory, `${agentId}.json`), 1024 * 1024))
      if (raw.version !== 1) return null
      const session = strictPersistedRow(raw.session)
      return session?.agentId === agentId ? session : null
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
      throw new Error('Could not read the saved stopped harness.')
    }
  }

  /** The id of every saved record, readable or not (`list()` skips an unreadable one). No folder yet → none; any other error throws. */
  ids(): string[] {
    try {
      return readdirSync(this.directory).filter(name => name.endsWith('.json')).map(name => name.slice(0, -5))
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
      throw error
    }
  }

  list(): RegisteredSession[] {
    try {
      secureStateDirectory(this.directory, false)
      const ids = readdirSync(this.directory).filter(name => name.endsWith('.json')).map(name => name.slice(0, -5))
      const present = new Set(ids)
      for (const id of this.catalogCache.keys()) if (!present.has(id)) this.forgetCatalogRecord(id)
      return ids.flatMap(id => {
        try {
          const saved = this.catalogRecord(id)
          return saved ? [saved] : []
        } catch {
          this.forgetCatalogRecord(id)
          // One unreadable record must not hide the other saved harnesses.
          return []
        }
      })
    } catch (error) {
      this.catalogCache.clear()
      this.catalogCacheBytes = 0
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
      throw error
    }
  }

  /** Status snapshots repeatedly enumerate the same saved metadata. Recheck
   * every file's identity on every read, but only reopen/parse changed files.
   * Actions still use get(), which always performs a fresh guarded read. */
  private catalogRecord(agentId: string): RegisteredSession | null {
    if (!SAFE_ID.test(agentId)) return null
    const file = join(this.directory, `${agentId}.json`)
    const before = lstatSync(file, { bigint: true })
    const fingerprint = catalogFingerprint(before)
    const cached = this.catalogCache.get(agentId)
    const now = Date.now()
    // Some mounted filesystems have coarse timestamps. Bound reuse even when
    // their metadata cannot distinguish two writes; no background timer is needed.
    if (cached?.fingerprint === fingerprint && now >= cached.at && now - cached.at < CATALOG_CACHE_MS) {
      return structuredClone(cached.session)
    }
    this.forgetCatalogRecord(agentId)
    const session = this.get(agentId)
    const bytes = Number(before.size)
    if (session && this.catalogCache.size < CATALOG_CACHE_RECORDS
      && this.catalogCacheBytes + bytes <= CATALOG_CACHE_BYTES
      && catalogFingerprint(lstatSync(file, { bigint: true })) === fingerprint) {
      this.catalogCache.set(agentId, { fingerprint, bytes, at: now, session: structuredClone(session) })
      this.catalogCacheBytes += bytes
    }
    return session
  }

  private forgetCatalogRecord(agentId: string): void {
    const cached = this.catalogCache.get(agentId)
    if (!cached) return
    this.catalogCacheBytes -= cached.bytes
    this.catalogCache.delete(agentId)
  }

  save(session: RegisteredSession): void {
    if (!SAFE_ID.test(session.agentId)) throw new Error('Invalid stopped harness identity.')
    // An exited engine leaves its pane as a shell. Stopping that shell must keep
    // the conversation saved before releaseEngine cleared its binding/profile.
    const previous = this.get(session.agentId)
    if (isTerminalEngine(session.engine) && previous) return
    // A temporarily unbound observation of the SAME process cannot erase a known conversation.
    // A replacement process must earn its own binding; never carry history across PID reuse.
    if (!session.sessionId && previous?.sessionId && previous.engine === session.engine
      && session.registeredAt === previous.registeredAt
      && (session.codexHome ?? null) === (previous.codexHome ?? null)
      && (!session.hermesHome || session.hermesHome === previous.hermesHome)
      && sameProcessIdentity(session.processIdentity, previous.processIdentity)
      && session.processIdentity!.executable === previous.processIdentity!.executable) {
      session = { ...session, sessionId: previous.sessionId, transcriptPath: previous.transcriptPath,
        hermesHome: previous.hermesHome, boundAt: previous.boundAt, source: previous.source }
    }
    // With optional readers absent, Stop can capture a path the live row has not learned.
    // Hooks during its checkpoint and the final forget both save that pathless row. They
    // must not erase the captured path, or Close succeeds but Resume loses the conversation.
    if (session.sessionId && !session.transcriptPath && previous?.transcriptPath
      && session.sessionId === previous.sessionId && session.engine === previous.engine
      && session.registeredAt === previous.registeredAt
      && (session.codexHome ?? null) === (previous.codexHome ?? null)
      && (session.hermesHome ?? null) === (previous.hermesHome ?? null)
      && sameProcessIdentity(session.processIdentity, previous.processIdentity)
      && session.processIdentity!.executable === previous.processIdentity!.executable) {
      session = { ...session, transcriptPath: previous.transcriptPath }
    }
    secureStateDirectory(dirname(this.directory))
    secureStateDirectory(this.directory)
    const snapshot = {
      ...session,
      active: false,
      launch: { state: 'ready' },
      defaultName: projectDisplayName(session),
      touchedAt: Date.now(),
    }
    // A later Resume is an explicit new visit, never an instruction to close it again.
    delete snapshot.closePlan
    // A hold describes this daemon's current observation, never durable conversation evidence.
    delete snapshot.admissionHold
    delete snapshot.identityHold
    delete snapshot.interpretationHold
    delete snapshot.evidenceRevision
    // A snapshot without a tmux pane omits the legacy alias just like registry persistence.
    if (!snapshot.tmuxPane) delete (snapshot as Partial<RegisteredSession>).tmuxPane
    atomicWriteJson(join(this.directory, `${session.agentId}.json`), { version: 1, session: snapshot })
    this.forgetCatalogRecord(session.agentId)
  }

  /** Correct one field of an archive in place — the folder a Claude row drifted out of (cwdRepair.ts).
   *  Not `save`: that recomputes the name and stamps `touchedAt`, and a repair must not reorder the
   *  catalog or rename anything. Nothing else on the row changes. */
  patch(agentId: string, patch: Partial<Pick<RegisteredSession, 'cwd'>>): boolean {
    const saved = this.get(agentId)
    if (!saved) return false
    secureStateDirectory(dirname(this.directory))
    secureStateDirectory(this.directory)
    atomicWriteJson(join(this.directory, `${agentId}.json`), { version: 1, session: { ...saved, ...patch } })
    this.forgetCatalogRecord(agentId)
    return true
  }

  /** Reserve before tmux allocation. A crash between allocation and registry persistence
   * must not permit a second process under a new request/receipt ID. */
  beginResume(agentId: string): string | null {
    if (!SAFE_ID.test(agentId)) throw new Error('Invalid saved harness identity.')
    secureStateDirectory(dirname(this.directory))
    secureStateDirectory(this.directory)
    const file = join(this.directory, `${agentId}.resume`)
    let fd: number
    try { fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600) }
    catch (error) { if ((error as NodeJS.ErrnoException).code === 'EEXIST') return null; throw error }
    const token = randomUUID()
    try { writeFileSync(fd, JSON.stringify({ token })); fsyncSync(fd) } finally { closeSync(fd) }
    this.syncDirectory()
    return token
  }

  /**
   * When the reservation for this agent was taken, or null if there is none.
   *
   * The reservation's whole job is to outlive a crash, so the caller needs to know how long it has
   * been held: one taken by an operation that cannot still be running is protecting nothing, and a
   * harness whose reservation is never released can never be resumed again.
   */
  resumeReservedAt(agentId: string): number | null {
    if (!SAFE_ID.test(agentId)) return null
    try { return statSync(join(this.directory, `${agentId}.resume`)).mtimeMs } catch { return null }
  }

  /**
   * Clear only a verified outcome. Unknown allocation/readiness keeps its reservation.
   *
   * `token` asks for the reservation to be cleared only if it is still the caller's own, which can
   * only be answered by parsing the marker. Without one the caller is clearing it unconditionally,
   * so the CONTENTS are not parsed — a reservation left behind by a crash can be half-written, and
   * refusing to clear THAT is refusing exactly the case a takeover exists for. The file is still
   * opened the same guarded way either way, so a symlink or anything else unsafe in its place
   * fails closed rather than being unlinked on trust.
   */
  finishResume(agentId: string, token?: string): void {
    if (!SAFE_ID.test(agentId)) return
    const file = join(this.directory, `${agentId}.resume`)
    try {
      secureStateDirectory(this.directory, false)
      const marker = readPrivateStateFile(file, 1024)
      if (token !== undefined && JSON.parse(marker).token !== token) return
      unlinkSync(file)
      this.syncDirectory()
    } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
  }

  private syncDirectory(): void {
    syncStateDirectory(this.directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
  }

  /** Permanent deletion is separate from Stop, which always retains this record. */
  remove(agentId: string): void {
    if (!SAFE_ID.test(agentId)) throw new Error('Invalid stopped harness identity.')
    if (!this.get(agentId)) return
    unlinkSync(join(this.directory, `${agentId}.json`))
    this.forgetCatalogRecord(agentId)
    this.syncDirectory()
  }

  /**
   * Sets a record aside because another harness owns its conversation now (core/agents/conversationOwners.ts).
   * Moved into `superseded/`, never deleted, so a wrong owner can be put back by hand; a reservation it left
   * goes with it, since nothing can resume a record that is not listed. Null when there is no such record.
   */
  supersede(agentId: string): RegisteredSession | null {
    if (!SAFE_ID.test(agentId)) return null
    const saved = this.get(agentId)
    if (!saved) return null
    const aside = join(this.directory, 'superseded')
    secureStateDirectory(aside)
    renameSync(join(this.directory, `${agentId}.json`), join(aside, `${agentId}.json`))
    this.forgetCatalogRecord(agentId)
    this.finishResume(agentId)
    this.syncDirectory()
    return saved
  }

  /** Suppress archives whose identity or conversation is already running. */
  available(live: readonly RegisteredSession[]): RegisteredSession[] {
    const ids = new Set(live.map(session => session.agentId))
    const conversations = new Set(live.map(conversationKey))
    return this.list().filter(session => {
      const key = conversationKey(session)
      return !ids.has(session.agentId) && (key === null || !conversations.has(key))
    })
  }
}

export const stoppedAgents = new StoppedAgentStore()