Skip to content

The agent that grows with you

26.2 KB
Raw Blame
/**
 * The update marker `HERMES_HOME/.hermes-update-in-progress` (#50238), format v2.
 *
 * One file, shared by every updater (Python `hermes_cli/update_lock.py`, the Rust
 * `UpdateMarkerGuard`, `scripts/desktop-update/{windows.ps1,posix.sh}`) and this
 * Desktop. While it names a LIVE owner, a Desktop reopened mid-update must not
 * spawn a backend on the runtime being replaced, and no second update may start.
 *
 * Parsing and judging live in `update-marker-judge.ts` and follow the shared
 * corpus `tests/fixtures/update_marker_corpus.json` (A7 rules 4 and 7).
 *
 * A7 rule 3: this Desktop NEVER deletes or rewrites the marker. Node has no
 * portable kernel lock, so every read-judge-mutate (reclaim a dead claim,
 * withdraw a bridge) belongs to the checkout's script helper, which holds the
 * `<marker>.lock` sidecar for the whole decision (see
 * `updater/marker-helper.ts`). Electron reads, decides "running / not
 * running", and may exclusive-create its own bridge or the staged updater's
 * pre-write — an exclusive create can only succeed where no marker exists.
 *
 * Claims publish a complete body with an exclusive hard link (A3), so a
 * reader never sees a half-written claim; where links are unsupported the
 * O_EXCL fallback can expose an empty file for an instant, and readers treat
 * a 0-byte marker younger than 5 s as live.
 */

import fs from 'fs'
import { execFile, execFileSync } from 'node:child_process'
import { randomBytes } from 'node:crypto'
import path from 'path'

import {
  hasForeignLiveIdentity,
  identityStateSync,
  isLiveIdentity,
  type JudgeEnv,
  judgeMarkerText,
  type MarkerJudgement,
  RUN_ID_RE,
  type UpdateMarker,
  V1_MAX_AGE_S
} from './update-marker-judge'

export {
  CREATE_TIME_TOLERANCE_S,
  type IdentityState,
  judgeMarkerText,
  type MarkerJudgement,
  OWN_CT_EPSILON_S,
  parseUpdateMarker,
  type UpdateMarker,
  V1_MAX_AGE_S
} from './update-marker-judge'

/** Legacy ceiling, applied ONLY to identities without a comparable creation time. */
export const UPDATE_MARKER_MAX_AGE_MS = V1_MAX_AGE_S * 1000

/** How long a hand-off script has to take the bridge marker (C2). */
export const HANDOFF_CLAIM_TIMEOUT_MS = 20_000

/** A 0-byte marker this young is a claim being written, not garbage (A3). */
export const EMPTY_MARKER_GRACE_MS = 5_000

/** .NET ticks (100 ns since 0001-01-01) at the unix epoch. */
const DOTNET_UNIX_EPOCH_TICKS = 621_355_968_000_000_000

export function markerPath(hermesHome: string) {
  return path.join(hermesHome, '.hermes-update-in-progress')
}

// True only if a host process with this pid is currently alive. Signal 0 does
// not deliver a signal — it just probes existence/permission. ESRCH => dead;
// EPERM => alive but owned by another user (still "alive" for our purposes).
// NOT zombie-aware on its own; see `posixProcessState`.
export function isPidAlive(pid: number, kill: typeof process.kill = process.kill.bind(process)) {
  if (!Number.isInteger(pid) || pid <= 0) {
    return false
  }

  try {
    kill(pid, 0)

    return true
  } catch (err: any) {
    return Boolean(err && err.code === 'EPERM')
  }
}

/**
 * Single-letter process state (`ps` style) for a kill(0)-alive pid, or null
 * when it cannot be determined. A ZOMBIE answers signal 0 like a live process
 * (#77259, #120635, #125932). Failures return null (fail-open to alive).
 */
export function posixProcessState(pid: number): string | null {
  if (process.platform === 'linux') {
    try {
      const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8')
      const commEnd = stat.lastIndexOf(')')
      const state = commEnd >= 0 ? stat.slice(commEnd + 2, commEnd + 3) : ''

      return state || null
    } catch {
      return null
    }
  }

  if (process.platform === 'darwin') {
    try {
      const out = execFileSync('ps', ['-o', 'stat=', '-p', String(pid)], {
        encoding: 'utf8',
        timeout: 5000
      })

      return out.trim().charAt(0) || null
    } catch {
      return null
    }
  }

  return null
}

/**
 * `posixProcessState` for the update gate's async judgement: macOS asks `ps`
 * without blocking the main thread (Linux reads /proc, no spawn).
 */
export async function posixProcessStateAsync(pid: number): Promise<string | null> {
  if (process.platform !== 'darwin') {
    return posixProcessState(pid)
  }

  const out = await execFileText('ps', ['-o', 'stat=', '-p', String(pid)], { timeout: 5000 })

  return out?.trim().charAt(0) || null
}

/** Async `execFile` stdout, or null on any failure (spawn, exit, timeout). */
function execFileText(
  file: string,
  args: string[],
  options: { env?: NodeJS.ProcessEnv; timeout: number }
): Promise<string | null> {
  return new Promise(resolve => {
    execFile(file, args, { encoding: 'utf8', windowsHide: true, ...options }, (error, stdout) =>
      resolve(error ? null : String(stdout))
    ).stdin?.end()
  })
}

function isZombieState(state: string | null | undefined): boolean {
  return Boolean(state && state.toUpperCase().startsWith('Z'))
}

let linuxClockTicks: number | null = null

/** The async path's CLK_TCK: `getconf` once, off the main thread. */
async function linuxClockTicksAsync(): Promise<number> {
  if (linuxClockTicks === null) {
    linuxClockTicks = Number((await execFileText('getconf', ['CLK_TCK'], { timeout: 2000 }))?.trim()) || 100
  }

  return linuxClockTicks
}

function linuxCreateTime(pid: number): number | null {
  try {
    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8')

    const fields = stat
      .slice(stat.lastIndexOf(')') + 1)
      .trim()
      .split(/\s+/)

    // Field 22 of /proc/<pid>/stat (starttime, clock ticks since boot) is index
    // 19 once pid and comm are stripped.
    const ticks = Number(fields[19])
    const btime = Number(/^btime\s+(\d+)/m.exec(fs.readFileSync('/proc/stat', 'utf8'))?.[1])

    if (!Number.isFinite(ticks) || !Number.isFinite(btime)) {
      return null
    }

    if (linuxClockTicks === null) {
      try {
        linuxClockTicks =
          Number(execFileSync('getconf', ['CLK_TCK'], { encoding: 'utf8', timeout: 2000 }).trim()) || 100
      } catch {
        linuxClockTicks = 100
      }
    }

    return btime + ticks / linuxClockTicks
  } catch {
    return null
  }
}

/**
 * `ps -o lstart=` creation time (the macOS source; procps prints the same).
 * Printed in UTC and parsed as UTC (A1): local time is ambiguous for an hour
 * at every DST fall-back and can put a live owner 3600 s off its record.
 */
export function psCreateTime(pid: number): number | null {
  try {
    return parsePsLstart(execFileSync('ps', psLstartArgs(pid), { encoding: 'utf8', env: psLstartEnv(), timeout: 5000 }))
  } catch {
    return null
  }
}

/** {@link psCreateTime} without blocking the main thread (the update gate's probe). */
async function psCreateTimeAsync(pid: number): Promise<number | null> {
  return parsePsLstart(await execFileText('ps', psLstartArgs(pid), { env: psLstartEnv(), timeout: 5000 }))
}

function psLstartArgs(pid: number): string[] {
  return ['-o', 'lstart=', '-p', String(pid)]
}

function psLstartEnv(): NodeJS.ProcessEnv {
  return { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC0' }
}

function parsePsLstart(stdout: string | null): number | null {
  const out = String(stdout ?? '').trim()
  const ms = out ? Date.parse(`${out.replace(/\s+/g, ' ')} GMT`) : NaN

  return Number.isFinite(ms) ? ms / 1000 : null
}

/**
 * Windows creation time through CIM (A1): `Win32_Process.CreationDate` is read
 * with limited query rights, so it answers for SYSTEM, elevated and other-user
 * processes where `Get-Process .StartTime` is access-denied.
 */
function windowsCreateTimeCommand(pid: number): string[] {
  return [
    '-NoProfile',
    '-NonInteractive',
    '-Command',
    `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' -ErrorAction Stop).CreationDate.ToUniversalTime().Ticks`
  ]
}

function dotnetTicksToUnix(stdout: unknown): number | null {
  const ticks = Number(String(stdout ?? '').trim())

  return Number.isFinite(ticks) && ticks > 0 ? (ticks - DOTNET_UNIX_EPOCH_TICKS) / 1e7 : null
}

function ownCreateTime(): number | null {
  const ms = (process as { getCreationTime?: () => number | null }).getCreationTime?.()

  return typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? ms / 1000 : null
}

/**
 * Creation time (unix seconds) of a live pid, or null when it cannot be read.
 * Same sources as the Python/Rust/script writers: Linux /proc starttime +
 * btime, macOS `ps -o lstart=` (UTC), Windows `GetProcessTimes` (Electron's own
 * `process.getCreationTime()` for this process; CIM `CreationDate` otherwise).
 * A Windows foreign pid costs one powershell spawn: pollers wrap this in
 * `cachedCreateTimeProbe`.
 */
export async function processCreateTime(pid: number): Promise<number | null> {
  if (!isPidAlive(pid)) {
    return null
  }

  // Never a synchronous spawn here (it runs on the main thread while a marker
  // exists): Linux reads /proc, macOS and Windows ask ps / CIM asynchronously.
  if (process.platform === 'linux') {
    await linuxClockTicksAsync()

    return linuxCreateTime(pid)
  }

  if (process.platform === 'darwin') {
    return psCreateTimeAsync(pid)
  }

  if (process.platform !== 'win32') {
    return null
  }

  const own = pid === process.pid ? ownCreateTime() : null

  return (
    own ?? dotnetTicksToUnix(await execFileText('powershell.exe', windowsCreateTimeCommand(pid), { timeout: 15_000 }))
  )
}

/**
 * Synchronous variant for module-init callers (desktop-installation's repair
 * lock). On Windows a foreign pid costs one blocking powershell spawn, so only
 * use it on a rare path.
 */
export function processCreateTimeSync(pid: number): number | null {
  if (!isPidAlive(pid)) {
    return null
  }

  if (process.platform === 'linux') {
    return linuxCreateTime(pid)
  }

  if (process.platform === 'darwin') {
    return psCreateTime(pid)
  }

  if (process.platform !== 'win32') {
    return null
  }

  // Electron's own GetProcessTimes; plain Node (tests, tooling) has no
  // getCreationTime and falls through to CIM like any other pid.
  const own = pid === process.pid ? ownCreateTime() : null

  if (own !== null) {
    return own
  }

  try {
    return dotnetTicksToUnix(
      execFileSync('powershell.exe', windowsCreateTimeCommand(pid), {
        encoding: 'utf8',
        timeout: 15_000,
        windowsHide: true,
        stdio: ['ignore', 'pipe', 'ignore']
      })
    )
  } catch {
    return null
  }
}

export type CreateTimeProbe = (pid: number) => number | null | Promise<number | null>

/**
 * One creation-time probe per pid for the life of ONE waiter (A1) — on Windows
 * each probe is a powershell spawn, and the update gate polls every second.
 * Scope it to a single wait, never module-wide: only a fresh probe tells a
 * pid reused since the last wait from the owner it replaced.
 */
export function cachedCreateTimeProbe(probe: CreateTimeProbe = processCreateTime): CreateTimeProbe {
  const memo = new Map<number, Promise<number | null>>()

  return pid => {
    let hit = memo.get(pid)

    if (!hit) {
      hit = Promise.resolve(probe(pid))
      memo.set(pid, hit)
    }

    return hit
  }
}

/** This process's creation time without a spawn when Electron can tell it (plain Node probes). */
export function ownCreateTimeSync(): number | null {
  return ownCreateTime() ?? processCreateTimeSync(process.pid)
}

/**
 * The judge's identity rule (A7 rule 4) for a lock holder, synchronously, for
 * the module-init repair lock: our own pid is live only at this exact
 * incarnation, and an identity with no comparable creation time is live only
 * within the v1 ceiling counted from `writtenAtS` (the lock's mtime).
 * `createTime` lets a polling caller probe each holder once per wait.
 */
export function lockHolderIsLiveSync(
  pid: number,
  recordedCt: number | null,
  writtenAtS: number,
  createTime: (pid: number) => number | null = processCreateTimeSync
): boolean {
  return isLiveIdentity(
    identityStateSync(pid, recordedCt, writtenAtS, {
      ourPid: process.pid,
      ourCt: ownCreateTimeSync,
      isAlive: candidate => isPidAlive(candidate) && !isZombieState(posixProcessState(candidate)),
      createTime,
      nowS: Date.now() / 1000
    })
  )
}

export function formatCreateTime(seconds: number): string {
  return seconds.toFixed(3)
}

export interface MarkerProbeDeps {
  kill?: typeof process.kill
  /** Milliseconds since the epoch. */
  now?: () => number
  processState?: (pid: number) => string | null | Promise<string | null>
  createTime?: CreateTimeProbe
  /** The pid judged as "us" (A7 rule 4); default this process. */
  ownPid?: number
}

/** The host's process facts as a judge environment (A7 rule 4). */
export function hostJudgeEnv(deps: MarkerProbeDeps = {}): JudgeEnv {
  const createTime = deps.createTime || processCreateTime
  const ourPid = deps.ownPid ?? process.pid

  return {
    ourPid,
    ourCt: () => createTime(ourPid),
    isAlive: async pid =>
      isPidAlive(pid, deps.kill) && !isZombieState(await (deps.processState || posixProcessStateAsync)(pid)),
    createTime,
    nowS: (deps.now || Date.now)() / 1000
  }
}

export type MarkerInspection =
  | { state: 'absent' }
  /**
   * Someone else's update is running (a live identity that is not this
   * process), or a 0-byte claim is being written (`judgement` null, A3).
   */
  | {
      state: 'live'
      raw: Buffer
      marker: UpdateMarker | null
      ageMs: number
      livePid: number
      judgement: MarkerJudgement | null
    }
  /** A bridge of THIS process incarnation and nothing foreign alive in it. */
  | { state: 'ours'; raw: Buffer; marker: UpdateMarker; judgement: MarkerJudgement }
  /** Dead or malformed (`judgement` null for a stale 0-byte file). */
  | { state: 'dead'; raw: Buffer; marker: UpdateMarker | null; judgement: MarkerJudgement | null }

/** Read and judge the marker. Never touches it. */
export async function inspectUpdateMarker(hermesHome: string, deps: MarkerProbeDeps = {}): Promise<MarkerInspection> {
  const file = markerPath(hermesHome)
  const now = deps.now || Date.now
  let raw: Buffer

  try {
    raw = fs.readFileSync(file)
  } catch {
    return { state: 'absent' }
  }

  if (raw.length === 0) {
    let ageMs = Infinity

    try {
      ageMs = now() - fs.statSync(file).mtimeMs
    } catch {
      // Gone since the read: nothing to judge.
    }

    return ageMs < EMPTY_MARKER_GRACE_MS
      ? { state: 'live', raw, marker: null, ageMs: Math.max(0, ageMs), livePid: 0, judgement: null }
      : { state: 'dead', raw, marker: null, judgement: null }
  }

  const judgement = await judgeMarkerText(raw.toString('utf8'), hostJudgeEnv(deps))
  const { marker } = judgement

  if (!marker || judgement.verdict === 'malformed' || judgement.verdict === 'dead') {
    return { state: 'dead', raw, marker, judgement }
  }

  if (hasForeignLiveIdentity(judgement)) {
    const ownerForeign = judgement.ownerState === 'match' || judgement.ownerState === 'unknown'
    const livePid = ownerForeign ? marker.pid : (marker.delegate?.pid ?? marker.pid)

    return { state: 'live', raw, marker, ageMs: now() - marker.startedAt * 1000, livePid, judgement }
  }

  return { state: 'ours', raw, marker, judgement }
}

/**
 * `{ pid, ageMs }` while someone else's update is genuinely running, else
 * null. Read-only (A7 rule 3): a dead marker is left for the script helper /
 * the next claimant to reclaim under the lock.
 */
export async function readLiveUpdateMarker(hermesHome: string, deps: MarkerProbeDeps = {}) {
  const inspection = await inspectUpdateMarker(hermesHome, deps)

  if (inspection.state !== 'live') {
    return null
  }

  return {
    pid: inspection.livePid,
    ownerPid: inspection.marker?.pid ?? 0,
    ageMs: inspection.ageMs,
    startedAt: inspection.marker?.startedAt ?? null
  }
}

function markerBody(pid: number, startedAt: number, ct: number | null, runId?: string | null): string {
  const ctLine = ct === null ? '' : `ct:${formatCreateTime(ct)}\n`
  const runLine = runId ? `run:${runId}\n` : ''

  return `${pid}\n${startedAt}\n${ctLine}${runLine}`
}

/** What an exclusive create found instead of publishing. */
export interface ExistingMarker {
  state: 'dead' | 'ours'
  raw: Buffer
  /** The run id the existing claim carries (to withdraw a stale bridge of ours). */
  run: string | null
}

export interface ClaimResult {
  ok: boolean
  body?: string
  /** Set when a LIVE claim blocks ours. */
  owner?: { pid: number; ageMs: number } | null
  /** Set when a dead/malformed claim, or a stale bridge of this process, blocks ours. */
  existing?: ExistingMarker
  error?: string
}

/**
 * Pre-write for the staged Tauri updater (`hermes-setup.exe --update`): the
 * child IS the updater there, so the marker names its pid AND its creation
 * time. A v2 body takes this path off the v1 20-minute ceiling, lets the
 * updater adopt it as its own claim, and lets the `hermes update` it runs add
 * its delegate line. Exclusive create ONLY (A7 rule 3): over any existing
 * marker — live or dead — the pre-write is skipped and the staged updater
 * claims (and reclaims) for itself.
 */
export async function writeUpdateMarker(
  hermesHome: string,
  pid: number,
  { startedAt, ...deps }: MarkerProbeDeps & { startedAt?: number } = {}
): Promise<ClaimResult> {
  const acquiredAt =
    typeof startedAt === 'number' && Number.isInteger(startedAt)
      ? startedAt
      : Math.floor((deps.now || Date.now)() / 1000)

  const ct = await (deps.createTime || processCreateTime)(pid)

  return createMarkerExclusive(hermesHome, markerBody(pid, acquiredAt, ct), deps)
}

/** Log line for a staged-updater pre-write that was skipped (exclusive create lost). */
export function describeSkippedPrewrite(result: ClaimResult): string {
  if (result.owner) {
    return `an update owned by pid ${result.owner.pid || '(claim being written)'} holds the marker`
  }

  if (result.existing) {
    return `a ${result.existing.state} marker exists; the staged updater reclaims it under its own lock`
  }

  return result.error || 'unknown error'
}

const TMP_SIBLING_RE = /^\.hermes-update-in-progress\.(\d+)(?:\.\d+)?\.tmp$/
let tmpSequence = 0

/**
 * Drop OUR publish tmp siblings (`<marker>.<pid>.<seq>.tmp`) whose writer died
 * between write and link. Never the marker itself.
 */
function reclaimDeadTmpSiblings(hermesHome: string) {
  try {
    for (const name of fs.readdirSync(hermesHome)) {
      const pid = Number(TMP_SIBLING_RE.exec(name)?.[1])

      if (pid && !isPidAlive(pid)) {
        fs.rmSync(path.join(hermesHome, name), { force: true })
      }
    }
  } catch {
    // Best effort: litter never blocks a claim.
  }
}

/**
 * Publish `body` at `file` only if nothing is there (A3): write a complete tmp
 * sibling, then hard-link it into place — link(2)/CreateHardLink fail with
 * EEXIST instead of replacing, and a reader never sees a partial body. A
 * filesystem without hard links falls back to O_EXCL create + write.
 */
function publishExclusive(file: string, body: string): 'published' | 'exists' {
  const tmp = `${file}.${process.pid}.${++tmpSequence}.tmp`
  let linked: boolean

  try {
    const fd = fs.openSync(tmp, 'wx', 0o644)

    try {
      fs.writeSync(fd, body)
      fs.fsyncSync(fd)
    } finally {
      fs.closeSync(fd)
    }

    try {
      fs.linkSync(tmp, file)
      linked = true
    } catch (error: any) {
      if (error?.code === 'EEXIST') {
        return 'exists'
      }

      linked = false
    }
  } finally {
    fs.rmSync(tmp, { force: true })
  }

  if (linked) {
    return 'published'
  }

  let fd: number

  try {
    fd = fs.openSync(file, 'wx', 0o644)
  } catch (error: any) {
    if (error?.code === 'EEXIST') {
      return 'exists'
    }

    throw error
  }

  try {
    fs.writeSync(fd, body)
    fs.fsyncSync(fd)
  } finally {
    fs.closeSync(fd)
  }

  return 'published'
}

/**
 * One exclusive create (A7 rule 2). On EEXIST the existing marker is judged
 * read-only and reported: a live owner blocks, a dead one / our own stale
 * bridge is handed back for the caller to route through the script helper.
 */
async function createMarkerExclusive(hermesHome: string, body: string, deps: MarkerProbeDeps): Promise<ClaimResult> {
  const file = markerPath(hermesHome)

  reclaimDeadTmpSiblings(hermesHome)

  try {
    if (publishExclusive(file, body) === 'published') {
      return { ok: true, body }
    }
  } catch (error: any) {
    return { ok: false, owner: null, error: error?.message || String(error) }
  }

  const inspection = await inspectUpdateMarker(hermesHome, deps)

  if (inspection.state === 'live') {
    return { ok: false, owner: { pid: inspection.livePid, ageMs: inspection.ageMs } }
  }

  if (inspection.state === 'absent') {
    // Withdrawn between our create and our read: the caller may retry once.
    return { ok: false, owner: null, error: 'the marker changed while it was being claimed' }
  }

  return {
    ok: false,
    owner: null,
    existing: { state: inspection.state, raw: inspection.raw, run: inspection.judgement?.run ?? null }
  }
}

function conflictMessage(owner: { pid: number; ageMs: number }): string {
  if (!owner.pid) {
    return 'Another update is starting right now. Wait for it to finish, then try again.'
  }

  const ageMs = Number.isFinite(owner.ageMs) ? Math.max(0, owner.ageMs) : 0
  const mins = Math.floor(ageMs / 60_000)
  const secs = Math.floor((ageMs % 60_000) / 1000)
  const elapsed = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`

  return `An update is already running (PID ${owner.pid}, started ${elapsed} ago). Wait for it to finish, then try again.`
}

/** A protocol-2 hand-off run id: `desk-<pid>-<base36 ms>-<hex4>` (run-line grammar). */
export function makeHandoffRunId(pid: number = process.pid, nowMs: number = Date.now()): string {
  const id = `desk-${pid}-${nowMs.toString(36)}-${randomBytes(2).toString('hex')}`

  if (!RUN_ID_RE.test(id)) {
    throw new Error(`invalid hand-off run id ${id}`)
  }

  return id
}

export interface BridgeClaimResult {
  ok: boolean
  body?: string
  /** A live foreign owner (or a claim being written) refuses the hand-off. */
  conflict?: { pid: number; ageMs: number; message: string } | null
  /** A dead/malformed marker or a stale bridge of ours blocks the create (protocol 2: script helper). */
  existing?: ExistingMarker
  error?: string
}

/**
 * C2 bridge claim, protocol 2 (SPEC 4a): the Desktop exclusive-creates the
 * marker in ITS OWN name (pid + creation time) with the hand-off `run:` line
 * before spawning the script. Never reclaims or overwrites anything (A7
 * rule 3): an existing marker is reported for the caller to route through
 * the checkout's script helper.
 */
export async function claimBridgeMarker(
  hermesHome: string,
  {
    pid = process.pid,
    createTime,
    startedAt,
    runId,
    ...deps
  }: MarkerProbeDeps & { pid?: number; startedAt?: number; runId?: string } = {}
): Promise<BridgeClaimResult> {
  const ct = await (createTime || processCreateTime)(pid)

  const acquiredAt =
    typeof startedAt === 'number' && Number.isInteger(startedAt)
      ? startedAt
      : Math.floor((deps.now || Date.now)() / 1000)

  const body = markerBody(pid, acquiredAt, ct, runId)

  fs.mkdirSync(hermesHome, { recursive: true })
  const result = await createMarkerExclusive(hermesHome, body, { ...deps, createTime, ownPid: deps.ownPid ?? pid })

  if (result.ok || !result.owner) {
    return { ok: result.ok, body: result.body, existing: result.existing, error: result.error }
  }

  return { ok: false, conflict: { ...result.owner, message: conflictMessage(result.owner) } }
}

export interface HandoffClaimOptions extends MarkerProbeDeps {
  /** Protocol 2: the run id passed to the script; the claim must carry it. */
  runId?: string
  /** Legacy scripts: the HERMES_UPDATE_STARTED_AT they echo on line 2. */
  startedAt?: number
  timeoutMs?: number
  pollMs?: number
  sleep?: (ms: number) => Promise<void>
}

/**
 * Whether the marker body proves a LIVE successor took the hand-off (R5,
 * A7 rule 6). Never the Desktop's own incarnation, never a dead or reused pid.
 * - protocol 2 (`runId`): line-1 owner verified by pid AND creation time
 *   (`match`, not `unknown`) and the claim's run == runId;
 * - legacy (`startedAt`): line-1 owner live (ct verified when recorded, else
 *   alive inside the v1 ceiling) and line 2 == the startedAt we passed.
 */
export async function handoffTakenBy(
  text: string,
  desktopPid: number,
  { runId, startedAt, ...deps }: HandoffClaimOptions
): Promise<number | null> {
  const judgement = await judgeMarkerText(text, hostJudgeEnv({ ...deps, ownPid: desktopPid }))
  const marker = judgement.marker

  if (!marker || marker.pid === desktopPid) {
    return null
  }

  if (runId !== undefined) {
    return judgement.ownerState === 'match' && marker.run === runId ? marker.pid : null
  }

  const live = judgement.ownerState === 'match' || judgement.ownerState === 'unknown'

  return live && (startedAt === undefined || marker.startedAt === startedAt) ? marker.pid : null
}

/**
 * C2 + R5: the hand-off has started only once a LIVE, correlated script
 * process holds the marker. A wrapper's exit code says nothing about whether
 * the script ever ran (#66753), and a pid that claimed then died is not a
 * running update.
 */
export async function waitForHandoffClaim(
  hermesHome: string,
  desktopPid: number,
  {
    timeoutMs = HANDOFF_CLAIM_TIMEOUT_MS,
    pollMs = 200,
    now = Date.now,
    sleep = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)),
    createTime,
    ...rest
  }: HandoffClaimOptions = {}
): Promise<{ taken: true; pid: number } | { taken: false }> {
  const deadline = now() + timeoutMs
  // One creation-time probe per pid for this wait (a powershell spawn on Windows).
  const probe = cachedCreateTimeProbe(createTime)

  for (;;) {
    let text: string | null = null

    try {
      text = fs.readFileSync(markerPath(hermesHome), 'utf8')
    } catch {
      text = null
    }

    const pid = text ? await handoffTakenBy(text, desktopPid, { ...rest, now, createTime: probe }) : null

    if (pid !== null) {
      return { taken: true, pid }
    }

    if (now() >= deadline) {
      return { taken: false }
    }

    await sleep(pollMs)
  }
}

/**
 * Whether a NEW updater hand-off must be refused because a different, live
 * updater owns the marker (#75778). Null when it is safe to spawn. Read-only.
 */
export async function updateHandoffConflict(hermesHome: string, deps: MarkerProbeDeps = {}) {
  const owner = await readLiveUpdateMarker(hermesHome, deps)

  return owner ? { pid: owner.pid, ageMs: owner.ageMs, message: conflictMessage(owner) } : null
}