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.

5.9 KB
Raw Blame
/**
 * Save an exact conversation identity while its native process still exists.
 *
 * Pause kills the engine, and afterwards there is nothing left to ask: the id the resume will need
 * has to be read out now. This runs for EVERY engine — it used to be claude and codex only, which is
 * why every other engine's pause archived whatever the registry happened to hold and its resume then
 * had nothing to reopen. `findLiveSession` already knows how to find a live session for all of them,
 * including the four that keep theirs in a database rather than a file.
 */
import { engineKeepsTranscriptFile, type RegisteredSession } from './registry.js'
import { controlTranscriptEvidence, savedTranscriptEvidence } from '../engines/transcriptBindings.js'
import { findLiveSession, findResumedTranscript, processSessionEvidence, type RepairedSession } from './sessionRepair.js'
import { resumeSessionId } from './processTable.js'
import { readProcessEvidence } from './processEvidence.js'
import { NativeEvidenceBudget, nativeUnavailable } from '../engines/kit/nativeEvidence.js'
import { IdentityReadUnavailable, ObservedConversationUnavailable } from '../engines/kit/identityScan.js'
import { isTerminalEngine } from '../engines/types.js'

export async function captureResumeIdentity(session: RegisteredSession, platform: NodeJS.Platform = process.platform): Promise<RegisteredSession> {
  // A shell holds no conversation; there is nothing here to capture for it.
  if (isTerminalEngine(session.engine)) return session
  const options = { codexHome: session.codexHome ?? undefined,
    ...(session.engine === 'pi' ? { cwd: session.cwd ?? undefined } : {}) }
  const keepsFile = engineKeepsTranscriptFile(session.engine)
  const verifiedPath = (id: string, path: string) => {
    const proof = savedTranscriptEvidence(session.engine, id, path, options.codexHome)
    proof.verify()
    if (proof.path) controlTranscriptEvidence(session.engine, id, proof.path, options.codexHome, session.cwd).verify()
    return proof.path
  }
  if (session.sessionId) {
    // A database-backed engine has the whole record already: the id IS the conversation.
    if (!keepsFile) return session
    if (session.transcriptPath) {
      const path = verifiedPath(session.sessionId, session.transcriptPath)
      if (path) return path === session.transcriptPath ? session : { ...session, transcriptPath: path }
    }
    const transcriptPath = await findResumedTranscript(session.engine, session.sessionId, options)
    const path = transcriptPath && verifiedPath(session.sessionId, transcriptPath)
    if (path) return { ...session, transcriptPath: path }
    if (session.engine === 'pi' && !session.transcriptPath) return session
    return nativeUnavailable('the saved conversation file is unavailable')
  }
  // Windows has neither ps nor lsof to read a live process with: a conversation there is known by its engine's hook, above, or
  // not at all. Refused, a Stop of a session at its first prompt said "the native ps probe did not complete" and left it running
  // (Copilot at its folder question on DESKTOP-0TFH0OJ, 2026-11-04).
  if (platform === 'win32') return session
  const expected = session.processIdentity
  if (!expected || !session.cwd) return session
  const budget = new NativeEvidenceBudget()
  const owner = await readProcessEvidence(expected.pid, budget, undefined, expected)
  const live = owner.parent
  if (!live) { await owner.verify(); return session }
  const explicit = resumeSessionId(session.engine, live.args, live.nativeArgv)
  // An engine whose process names its own session in a record (Claude Code's, removed at exit) is read now.
  const claim = await processSessionEvidence(session.engine, expected.pid, session.cwd, Date.parse(expected.startMarker), budget)
  const native = claim.session
  // Once a conversation is seen (a native record, a resume on the command line, one found live), a failure to read it
  // holds it: a close of a harness still starting may stop one whose conversation was never seen, never this one.
  let seen = !!native || !!explicit
  const cwd = session.cwd
  const capture = async (): Promise<RegisteredSession> => {
    const found: RepairedSession | null = native ?? (explicit
      ? { sessionId: explicit, transcriptPath: await findResumedTranscript(session.engine, explicit, options) ?? undefined }
      : await findLiveSession(session.engine, cwd, Date.parse(expected.startMarker), {
        ...options, hermesHome: session.hermesHome ?? undefined, pid: expected.pid, bornOnly: true,
        ...(session.forkedFrom?.sessionId ? { excludedSessionId: session.forkedFrom.sessionId } : {}),
        expectedProcess: expected, nativeBudget: budget,
      }))
    seen ||= !!found?.sessionId
    // Codex's open-file finder verifies this owner, all candidate headers and its descriptor
    // pool together. Other finders still need this final process fence before a Stop may proceed.
    if (native || explicit || session.engine !== 'codex') await owner.verify()
    claim.verify()
    if (!found?.sessionId) return session
    // A file-backed engine still has to produce a transcript this daemon can point a resume at; a
    // database-backed one has nothing to check and is taken on its id alone.
    const transcriptPath = found.transcriptPath && keepsFile ? verifiedPath(found.sessionId, found.transcriptPath) : found.transcriptPath
    if (keepsFile && !transcriptPath) return nativeUnavailable('the observed conversation file is unavailable')
    return {
      ...session,
      sessionId: found.sessionId,
      ...(transcriptPath ? { transcriptPath } : {}),
      ...(found.hermesHome ? { hermesHome: found.hermesHome } : {}),
      source: 'stop-repair',
      boundAt: Date.now(),
    }
  }
  try { return await capture() } catch (error) {
    if (!seen || !(error instanceof IdentityReadUnavailable) || error instanceof ObservedConversationUnavailable) throw error
    throw new ObservedConversationUnavailable(error.message)
  }
}