spexcode 0.5.2 → 0.5.4

package/spec-cli/src/session-maintenance.ts

@@ -0,0 +1,750 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { execFileSync } from 'node:child_process'
+import { createHash, randomBytes as cryptoRandomBytes, timingSafeEqual } from 'node:crypto'
+import { closeSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { join } from 'node:path'
+import { runtimeRoot as projectRuntimeRoot } from './layout.js'
+import { parseProcStat, processStartToken } from './process-identity.js'
+
+export type ProcessIdentity = { pid: number; startToken: string }
+export type LeaseOwner = ProcessIdentity & { instanceId: string }
+export type ProcessReading = ProcessIdentity | null | 'ambiguous'
+export type Capability =
+  | { op: 'stop'; sessionId: string }
+  | { op: 'resume'; sessionId: string; force: boolean }
+export type Authorization = { token: string; epoch: number }
+export type Operation =
+  | { op: 'create' }
+  | { op: 'fallback-create' }
+  | { op: 'lifecycle-transition'; sessionId: string }
+  | { op: 'hook-state'; sessionId: string }
+  | { op: 'send'; sessionId: string }
+  | { op: 'raw-key-input'; sessionId: string }
+  | { op: 'terminal-input'; sessionId: string }
+  | { op: 'interrupt'; sessionId: string }
+  | { op: 'rename'; sessionId: string }
+  | { op: 'sort'; sessionId: string }
+  | ({ op: 'stop'; sessionId: string } & Partial<{ authorization: Authorization }>)
+  | ({ op: 'resume'; sessionId: string; force: boolean } & Partial<{ authorization: Authorization }>)
+  | { op: 'archive'; sessionId: string }
+  | { op: 'close'; sessionId: string }
+  | { op: 'merge-dispatch'; sessionId: string }
+  | { op: 'queue-drain' }
+  | { op: 'attach'; sessionId: string }
+  | { op: 'shared-spawn'; sessionId: string; delegate?: string }
+
+type CapabilityState = 'unused' | 'inflight' | 'committed' | 'indeterminate'
+type CapabilityEntry = { capability: Capability; state: CapabilityState; requestId?: string }
+type Ticket = {
+  id: string
+  epoch: number
+  operation: Operation['op']
+  sessionId?: string
+  force?: boolean
+  owner: ProcessIdentity
+  deadline: number
+  mode?: 'ordinary' | 'maintenance'
+  parentTicketId?: string
+}
+type Delegate = {
+  tokenHash: string
+  parentTicketId: string
+  epoch: number
+  operation: 'shared-spawn'
+  sessionId: string
+  state: 'unused' | 'running' | 'completed'
+}
+type DurableState = {
+  version: 1
+  state: 'open' | 'draining' | 'active'
+  epoch: number
+  tokenHash: string | null
+  owner: LeaseOwner | null
+  heartbeatDeadline: number | null
+  capabilities: CapabilityEntry[]
+  tickets: Ticket[]
+  delegates: Delegate[]
+}
+export type MaintenanceTicket = {
+  id: string
+  epoch: number
+  delegateSharedSpawn(sessionId: string): string
+}
+export type MaintenanceLease = {
+  token: string
+  epoch: number
+  state: 'draining' | 'active'
+  owner: LeaseOwner
+  capabilities: readonly Capability[]
+}
+export type MaintenanceState = {
+  state: DurableState['state']
+  epoch: number
+  owner: LeaseOwner | null
+  heartbeatDeadline: number | null
+  tickets: readonly {
+    operation: Operation['op']
+    sessionId?: string
+    force?: boolean
+    owner: ProcessIdentity
+    deadline: number
+  }[]
+  capabilities: readonly CapabilityEntry[]
+}
+
+type CoordinatorInput = {
+  runtimeRoot: string
+  now: () => number
+  randomBytes: (size: number) => Buffer
+  processIdentity: (pid: number) => ProcessReading
+  selfIdentity: () => ProcessIdentity
+  ticketReportMs: number
+  onEvent?: (event: Record<string, unknown>) => void
+}
+
+const OPERATIONS = new Set<Operation['op']>([
+  'create', 'fallback-create', 'lifecycle-transition', 'hook-state', 'send', 'raw-key-input',
+  'terminal-input', 'interrupt', 'rename', 'sort', 'stop', 'resume', 'archive', 'close',
+  'merge-dispatch', 'queue-drain', 'attach', 'shared-spawn',
+])
+const MIN_TTL_MS = 5_000
+const MAX_TTL_MS = 300_000
+const MAX_WAIT_MS = 120_000
+const LOCK_WAIT_MS = 5_000
+const syncPause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+const context = new AsyncLocalStorage<{ ticketId: string }>()
+
+export class SessionMaintenanceError extends Error {
+  readonly code: string
+  readonly state?: DurableState['state']
+  readonly epoch?: number
+  readonly operation?: Operation['op']
+  readonly sessionId?: string
+
+  constructor(code: string, message: string, details: Partial<Pick<SessionMaintenanceError, 'state' | 'epoch' | 'operation' | 'sessionId'>> = {}) {
+    super(message)
+    this.name = 'SessionMaintenanceError'
+    this.code = code
+    Object.assign(this, details)
+  }
+}
+
+const fail = (code: string, message: string, details?: Partial<Pick<SessionMaintenanceError, 'state' | 'epoch' | 'operation' | 'sessionId'>>): never => {
+  throw new SessionMaintenanceError(code, message, details)
+}
+const emptyState = (): DurableState => ({
+  version: 1, state: 'open', epoch: 0, tokenHash: null, owner: null, heartbeatDeadline: null,
+  capabilities: [], tickets: [], delegates: [],
+})
+const copy = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T
+const hashToken = (token: string): string => createHash('sha256').update(token).digest('hex')
+const sameIdentity = (a: ProcessIdentity | null | undefined, b: ProcessIdentity | null | undefined): boolean =>
+  !!a && !!b && a.pid === b.pid && a.startToken === b.startToken
+const operationSession = (operation: Operation): string | undefined => 'sessionId' in operation ? operation.sessionId : undefined
+const operationForce = (operation: Operation): boolean | undefined => operation.op === 'resume' ? operation.force : undefined
+
+function canonicalCapabilities(input: readonly Capability[]): Capability[] {
+  if (!Array.isArray(input)) fail('maintenance_invalid', 'maintenance capabilities must be an array')
+  const seen = new Set<string>()
+  return input.map((raw) => {
+    if (!raw || typeof raw !== 'object' || typeof raw.sessionId !== 'string' || !raw.sessionId.trim())
+      fail('maintenance_invalid', 'maintenance capability needs an exact session id')
+    const capability: Capability = raw.op === 'stop' && Object.keys(raw).every((key) => key === 'op' || key === 'sessionId')
+      ? { op: 'stop', sessionId: raw.sessionId }
+      : raw.op === 'resume' && typeof raw.force === 'boolean'
+        && Object.keys(raw).every((key) => key === 'op' || key === 'sessionId' || key === 'force')
+        ? { op: 'resume', sessionId: raw.sessionId, force: raw.force }
+        : fail('maintenance_invalid', 'maintenance capability must be exact stop or resume authority')
+    const key = `${capability.op}\0${capability.sessionId}`
+    if (seen.has(key)) fail('maintenance_invalid', `duplicate maintenance capability for ${capability.op} ${capability.sessionId}`)
+    seen.add(key)
+    return capability
+  })
+}
+
+function normalizeState(raw: unknown): DurableState {
+  if (!raw || typeof raw !== 'object') fail('maintenance_state_invalid', 'session maintenance state is unreadable')
+  const value = raw as Partial<DurableState>
+  if (value.version !== 1 || !['open', 'draining', 'active'].includes(String(value.state)) || !Number.isSafeInteger(value.epoch) || Number(value.epoch) < 0)
+    fail('maintenance_state_invalid', 'session maintenance state has an invalid version, state, or epoch')
+  return {
+    version: 1,
+    state: value.state as DurableState['state'],
+    epoch: Number(value.epoch),
+    tokenHash: typeof value.tokenHash === 'string' ? value.tokenHash : null,
+    owner: value.owner && typeof value.owner.instanceId === 'string' && value.owner.instanceId
+      && Number.isInteger(value.owner.pid) && typeof value.owner.startToken === 'string'
+      ? copy(value.owner as LeaseOwner)
+      : null,
+    heartbeatDeadline: typeof value.heartbeatDeadline === 'number' ? value.heartbeatDeadline : null,
+    capabilities: Array.isArray(value.capabilities) ? copy(value.capabilities) : [],
+    tickets: Array.isArray(value.tickets) ? copy(value.tickets) : [],
+    delegates: Array.isArray(value.delegates) ? copy(value.delegates) : [],
+  }
+}
+
+function presentedTokenMatches(token: string, expectedHash: string | null): boolean {
+  const actual = createHash('sha256').update(token).digest()
+  const valid = typeof expectedHash === 'string' && /^[0-9a-f]{64}$/i.test(expectedHash)
+  const expected = valid ? Buffer.from(expectedHash!, 'hex') : Buffer.alloc(actual.length)
+  return timingSafeEqual(actual, expected) && valid
+}
+
+function parentPid(pid: number): number | null {
+  if (platform() === 'linux') {
+    try { return parseProcStat(readFileSync(`/proc/${pid}/stat`, 'utf8')).ppid } catch { return null }
+  }
+  try {
+    const value = Number(execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf8' }).trim())
+    return Number.isInteger(value) && value > 0 ? value : null
+  } catch { return null }
+}
+
+function isDescendantOf(pid: number, owner: ProcessIdentity, readIdentity: (pid: number) => ProcessReading): boolean {
+  const ownerReading = readIdentity(owner.pid)
+  if (ownerReading === 'ambiguous' || !sameIdentity(ownerReading, owner)) return false
+  let current = pid
+  for (let depth = 0; depth < 64 && current > 1; depth++) {
+    if (current === owner.pid) return true
+    const parent = parentPid(current)
+    if (!parent || parent === current) return false
+    current = parent
+  }
+  return false
+}
+
+export function createSessionMaintenance(input: CoordinatorInput) {
+  const statePath = join(input.runtimeRoot, 'session-maintenance.json')
+  const lockPath = join(input.runtimeRoot, '.session-maintenance.lock')
+  const lockPrefix = '.session-maintenance.lock.reap-'
+  mkdirSync(input.runtimeRoot, { recursive: true })
+
+  const identityState = (owner: ProcessIdentity): 'live' | 'dead' | 'reused' | 'ambiguous' => {
+    const reading = input.processIdentity(owner.pid)
+    if (reading === 'ambiguous') return 'ambiguous'
+    if (reading === null) return 'dead'
+    return sameIdentity(reading, owner) ? 'live' : 'reused'
+  }
+
+  type LockRecord = { version: 1; nonce: string; owner: ProcessIdentity }
+  const readLock = (path = lockPath): LockRecord | null => {
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<LockRecord>
+      return raw.version === 1 && typeof raw.nonce === 'string' && raw.nonce
+        && raw.owner && Number.isInteger(raw.owner.pid) && typeof raw.owner.startToken === 'string'
+        ? raw as LockRecord
+        : null
+    } catch { return null }
+  }
+  const writeLinkedRecord = (path: string, record: LockRecord): boolean => {
+    const temp = join(input.runtimeRoot, `.session-maintenance.owner-${process.pid}-${record.nonce}.tmp`)
+    let fd: number | null = null
+    try {
+      fd = openSync(temp, 'wx', 0o600)
+      writeFileSync(fd, JSON.stringify(record))
+      fsyncSync(fd)
+      closeSync(fd); fd = null
+      linkSync(temp, path)
+      return true
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+      return false
+    } finally {
+      if (fd !== null) closeSync(fd)
+      try { unlinkSync(temp) } catch { /* linked or already absent */ }
+    }
+  }
+  const reapMarkers = (): string[] => {
+    try { return readdirSync(input.runtimeRoot).filter((name) => name.startsWith(lockPrefix)) }
+    catch { return [] }
+  }
+  const sameLockRecord = (left: LockRecord | null, right: LockRecord): boolean =>
+    !!left && left.nonce === right.nonce && sameIdentity(left.owner, right.owner)
+  const reclaimDeadRecord = (path: string, expected: LockRecord, depth = 0): boolean => {
+    if (depth >= 64) fail('maintenance_conflict', 'session maintenance lock claim depth exceeded')
+    if (!sameLockRecord(readLock(path), expected) || !['dead', 'reused'].includes(identityState(expected.owner))) return false
+    const claimPath = `${path}.claim`
+    const self = input.selfIdentity()
+    const claim: LockRecord = { version: 1, nonce: input.randomBytes(16).toString('hex'), owner: self }
+    if (!writeLinkedRecord(claimPath, claim)) {
+      const existing = readLock(claimPath)
+      if (!existing || !['dead', 'reused'].includes(identityState(existing.owner))) return false
+      if (!reclaimDeadRecord(claimPath, existing, depth + 1)) return false
+      return reclaimDeadRecord(path, expected, depth + 1)
+    }
+    try {
+      const confirmed = readLock(path)
+      if (!sameLockRecord(confirmed, expected) || !['dead', 'reused'].includes(identityState(expected.owner))) return false
+      unlinkSync(path)
+      return true
+    } finally {
+      if (sameLockRecord(readLock(claimPath), claim)) unlinkSync(claimPath)
+    }
+  }
+  const clearDeadMarkers = (): boolean => {
+    for (const name of reapMarkers()) {
+      const path = join(input.runtimeRoot, name)
+      const marker = readLock(path)
+      if (marker && ['dead', 'reused'].includes(identityState(marker.owner))) reclaimDeadRecord(path, marker)
+    }
+    return reapMarkers().length === 0
+  }
+
+  const acquireLock = (): (() => void) => {
+    const deadline = Date.now() + LOCK_WAIT_MS
+    const self = input.selfIdentity()
+    const nonce = input.randomBytes(16).toString('hex')
+    const own: LockRecord = { version: 1, nonce, owner: self }
+    for (;;) {
+      if (clearDeadMarkers() && writeLinkedRecord(lockPath, own)) {
+        return () => {
+          const current = readLock()
+          if (!current || current.nonce !== nonce || !sameIdentity(current.owner, self))
+            fail('maintenance_conflict', 'session maintenance lock ownership changed before release')
+          unlinkSync(lockPath)
+        }
+      }
+
+      const current = readLock()
+      if (!current) {
+        // Legacy mkdir-before-owner residue is the old crash window this protocol removes. It has no
+        // complete identity that can authorize a state mutation, so remove only an empty directory.
+        try { if (readdirSync(lockPath).length === 0) rmSync(lockPath, { recursive: true }) } catch { /* file or live legacy owner */ }
+      } else if (['dead', 'reused'].includes(identityState(current.owner))) {
+        const markerPath = join(input.runtimeRoot, `${lockPrefix}${current.nonce}`)
+        const marker: LockRecord = { version: 1, nonce: input.randomBytes(16).toString('hex'), owner: self }
+        if (writeLinkedRecord(markerPath, marker)) {
+          try {
+            const confirmed = readLock()
+            if (confirmed?.nonce === current.nonce && sameIdentity(confirmed.owner, current.owner)
+              && ['dead', 'reused'].includes(identityState(confirmed.owner))) unlinkSync(lockPath)
+          } finally {
+            const claim = readLock(markerPath)
+            if (claim?.nonce === marker.nonce && sameIdentity(claim.owner, self)) unlinkSync(markerPath)
+          }
+          continue
+        }
+      }
+      if (Date.now() >= deadline) fail('maintenance_conflict', 'session maintenance state lock is held by a live or ambiguous owner')
+      syncPause(5)
+    }
+  }
+
+  const load = (): { state: DurableState; exists: boolean } => {
+    if (!existsSync(statePath)) return { state: emptyState(), exists: false }
+    try { return { state: normalizeState(JSON.parse(readFileSync(statePath, 'utf8'))), exists: true } }
+    catch (error) {
+      if (error instanceof SessionMaintenanceError) throw error
+      return fail('maintenance_state_invalid', `session maintenance state is unreadable: ${(error as Error).message}`)
+    }
+  }
+  const persist = (state: DurableState): void => {
+    const temp = `${statePath}.${process.pid}.${Date.now()}.tmp`
+    writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
+    renameSync(temp, statePath)
+  }
+
+  const recover = (state: DurableState, protectedTicketId?: string): boolean => {
+    let dirty = false
+    const retained: Ticket[] = []
+    for (const ticket of state.tickets) {
+      const ownerState = ticket.id === protectedTicketId ? 'live' : identityState(ticket.owner)
+      if (ownerState === 'live' || ownerState === 'ambiguous') {
+        retained.push(ticket)
+        continue
+      }
+      dirty = true
+      if (ticket.mode === 'maintenance') {
+        const entry = state.capabilities.find(({ capability }) => capability.op === ticket.operation
+          && capability.sessionId === ticket.sessionId
+          && (capability.op !== 'resume' || capability.force === ticket.force))
+        if (entry?.state === 'inflight' && entry.requestId === ticket.id) {
+          entry.state = 'indeterminate'
+          delete entry.requestId
+        }
+      }
+      for (const delegate of state.delegates) if (delegate.parentTicketId === ticket.id && delegate.state !== 'completed') delegate.state = 'completed'
+    }
+    if (retained.length !== state.tickets.length) state.tickets = retained
+
+    if (state.state !== 'open' && state.tokenHash && state.owner) {
+      const ownerState = identityState(state.owner)
+      if (ownerState === 'dead' || ownerState === 'reused' || input.now() > (state.heartbeatDeadline ?? -Infinity)) {
+        state.state = 'draining'
+        state.tokenHash = null
+        state.owner = null
+        state.heartbeatDeadline = null
+        for (const entry of state.capabilities) if (entry.state === 'inflight') {
+          entry.state = 'indeterminate'
+          delete entry.requestId
+        }
+        dirty = true
+      }
+    }
+    if (state.state === 'draining' && state.tickets.length === 0) {
+      if (state.tokenHash && state.owner && input.now() <= (state.heartbeatDeadline ?? -Infinity)) state.state = 'active'
+      else {
+        state.state = 'open'
+        state.tokenHash = null
+        state.owner = null
+        state.heartbeatDeadline = null
+        state.capabilities = []
+        state.delegates = []
+      }
+      dirty = true
+    }
+    return dirty
+  }
+
+  const locked = <T>(body: (state: DurableState, dirty: () => void) => T, beforeRecover?: (state: DurableState) => string | undefined): T => {
+    const release = acquireLock()
+    try {
+      const loaded = load()
+      let changed = !loaded.exists
+      const protectedTicketId = beforeRecover?.(loaded.state)
+      if (recover(loaded.state, protectedTicketId)) changed = true
+      const value = body(loaded.state, () => { changed = true })
+      if (changed) persist(loaded.state)
+      return value
+    } finally { release() }
+  }
+
+  locked((_state, dirty) => { if (!existsSync(statePath)) dirty() })
+
+  const verifyLease = (state: DurableState, authorization: Authorization): void => {
+    if (state.state !== 'active' || authorization.epoch !== state.epoch)
+      fail('maintenance_conflict', 'maintenance lease epoch is not active', { state: state.state, epoch: state.epoch })
+    if (!presentedTokenMatches(authorization.token, state.tokenHash))
+      fail('maintenance_token_invalid', 'maintenance bearer is missing, wrong, or stale', { state: state.state, epoch: state.epoch })
+  }
+  const capabilityFor = (state: DurableState, operation: Operation) => state.capabilities.find(({ capability }) =>
+    capability.op === operation.op && capability.sessionId === operationSession(operation)
+    && (capability.op !== 'resume' || capability.force === operationForce(operation)))
+
+  const inheritedOrdinaryParent = (state: DurableState): Ticket | null => {
+    const local = context.getStore()?.ticketId
+    const inherited = process.env.SPEXCODE_MAINTENANCE_PARENT_TICKET?.trim()
+    const id = local || inherited
+    if (!id) return null
+    const ticket = state.tickets.find((candidate) => candidate.id === id && candidate.mode !== 'maintenance')
+    if (!ticket) return null
+    if (local) return ticket
+    return isDescendantOf(process.pid, ticket.owner, input.processIdentity) ? ticket : null
+  }
+
+  const sharedSpawnAuthority = (state: DurableState, operation: Extract<Operation, { op: 'shared-spawn' }>): { delegate: Delegate; parentTicket: Ticket } => {
+    const raw = 'delegate' in operation ? operation.delegate : undefined
+    const delegate = typeof raw === 'string' ? state.delegates.find((candidate) => candidate.epoch === state.epoch
+      && candidate.operation === 'shared-spawn' && candidate.sessionId === operation.sessionId
+      && presentedTokenMatches(raw, candidate.tokenHash)) : undefined
+    const parentTicket = delegate && state.tickets.find((candidate) => candidate.id === delegate.parentTicketId
+      && candidate.epoch === state.epoch && candidate.operation === 'resume'
+      && candidate.sessionId === operation.sessionId && candidate.mode === 'maintenance')
+    if (!delegate || delegate.state !== 'unused' || !parentTicket || identityState(parentTicket.owner) !== 'live')
+      return fail('maintenance_delegate_invalid', 'shared-runtime delegate is forged, stale, completed, mismatched, replayed, or detached from its live resume owner', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+    return { delegate, parentTicket }
+  }
+
+  const beginTicket = (state: DurableState, operation: Operation, owner: ProcessIdentity, markDirty: () => void): Ticket => {
+    if (!OPERATIONS.has(operation.op)) fail('maintenance_invalid', `unknown maintenance operation ${(operation as { op?: string }).op ?? ''}`)
+    const parent = inheritedOrdinaryParent(state)
+    const ticketId = input.randomBytes(16).toString('hex')
+    let mode: Ticket['mode'] = 'ordinary'
+    let parentTicketId: string | undefined
+
+    if (operation.op === 'shared-spawn') {
+      if (state.state === 'open') {
+        if ('delegate' in operation) fail('maintenance_delegate_invalid', 'shared-runtime delegate channel is not valid outside active maintenance', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+      } else if (state.state !== 'active') {
+        fail('maintenance_active', `session maintenance is ${state.state}; shared-spawn was not admitted`, { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+      } else {
+        const { delegate, parentTicket } = sharedSpawnAuthority(state, operation)
+        delegate.state = 'running'
+        mode = 'maintenance'
+        parentTicketId = parentTicket.id
+      }
+    } else if ((operation.op === 'stop' || operation.op === 'resume') && operation.authorization) {
+      verifyLease(state, operation.authorization)
+      const entry = capabilityFor(state, operation)
+      if (!entry) return fail('maintenance_capability_missing', 'operation is not in the exact maintenance capability plan', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+      if (entry.state !== 'unused') fail('maintenance_capability_used', 'maintenance capability is already inflight, committed, or indeterminate', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+      entry.state = 'inflight'
+      entry.requestId = ticketId
+      mode = 'maintenance'
+    } else if (state.state !== 'open' && (operation.op === 'stop' || operation.op === 'resume')) {
+      if (state.state === 'active')
+        return fail('maintenance_token_invalid', 'maintenance bearer is missing, wrong, or stale', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+      fail('maintenance_active', `session maintenance is ${state.state}; ${operation.op} was not admitted`, { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operation.sessionId })
+    } else if (state.state === 'active' && 'authorization' in operation && operation.authorization) {
+      verifyLease(state, operation.authorization)
+      fail('maintenance_capability_missing', 'operation is not in the exact maintenance capability plan', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operationSession(operation) })
+    } else if (state.state !== 'open' && parent) parentTicketId = parent.id
+    else if (state.state !== 'open') {
+      if ('delegate' in operation) fail('maintenance_delegate_invalid', 'shared-runtime delegate is not valid for this operation', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operationSession(operation) })
+      fail('maintenance_active', `session maintenance is ${state.state}; ${operation.op} was not admitted`, { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operationSession(operation) })
+    }
+
+    const ticket: Ticket = {
+      id: ticketId, epoch: state.epoch, operation: operation.op,
+      ...(operationSession(operation) ? { sessionId: operationSession(operation) } : {}),
+      ...(operationForce(operation) !== undefined ? { force: operationForce(operation) } : {}),
+      owner, deadline: input.now() + input.ticketReportMs, mode,
+      ...(parentTicketId ? { parentTicketId } : {}),
+    }
+    state.tickets.push(ticket)
+    markDirty()
+    return ticket
+  }
+
+  const beginOperationTicket = (operation: Operation, owner: ProcessIdentity): Ticket => locked(
+    (state, dirty) => beginTicket(state, operation, owner, dirty),
+    (state) => {
+      if (operation.op !== 'shared-spawn' || state.state !== 'active') return undefined
+      // Protect the proven-live parent from recovery, then re-read it in beginTicket before delegate mutation.
+      return sharedSpawnAuthority(state, operation).parentTicket.id
+    },
+  )
+
+  const finishTicket = (ticketId: string, outcome: 'committed' | 'retryable' | 'indeterminate'): void => locked((state, dirty) => {
+    const index = state.tickets.findIndex((ticket) => ticket.id === ticketId)
+    if (index < 0) return
+    const [ticket] = state.tickets.splice(index, 1)
+    if (ticket.mode === 'maintenance' && (ticket.operation === 'stop' || ticket.operation === 'resume')) {
+      const entry = state.capabilities.find(({ capability }) => capability.op === ticket.operation
+        && capability.sessionId === ticket.sessionId && (capability.op !== 'resume' || capability.force === ticket.force))
+      if (entry?.state === 'inflight' && entry.requestId === ticket.id) {
+        entry.state = outcome === 'retryable' ? 'unused' : outcome
+        delete entry.requestId
+      }
+    }
+    if (ticket.operation === 'shared-spawn' && ticket.parentTicketId) {
+      const delegate = state.delegates.find((candidate) => candidate.parentTicketId === ticket.parentTicketId
+        && candidate.sessionId === ticket.sessionId && candidate.state === 'running')
+      if (delegate) delegate.state = 'completed'
+    }
+    dirty()
+  })
+
+  const delegateForTicket = (ticketId: string, sessionId: string): string => locked((state, dirty) => {
+    const ticket = state.tickets.find((candidate) => candidate.id === ticketId && candidate.operation === 'resume'
+      && candidate.mode === 'maintenance' && candidate.sessionId === sessionId && candidate.epoch === state.epoch)
+    if (!ticket || state.state !== 'active') return fail('maintenance_delegate_invalid', 'resume ticket is not live for this session')
+    if (state.delegates.some((delegate) => delegate.parentTicketId === ticket.id))
+      fail('maintenance_delegate_invalid', 'resume ticket already delegated its shared spawn')
+    const token = input.randomBytes(32).toString('hex')
+    state.delegates.push({ tokenHash: hashToken(token), parentTicketId: ticket.id, epoch: state.epoch, operation: 'shared-spawn', sessionId, state: 'unused' })
+    dirty()
+    return token
+  })
+
+  const readState = (): MaintenanceState => locked((state) => ({
+    state: state.state,
+    epoch: state.epoch,
+    owner: copy(state.owner),
+    heartbeatDeadline: state.heartbeatDeadline,
+    tickets: copy(state.tickets.map((ticket) => ({
+      operation: ticket.operation,
+      ...(ticket.sessionId ? { sessionId: ticket.sessionId } : {}),
+      ...(ticket.force !== undefined ? { force: ticket.force } : {}),
+      owner: ticket.owner,
+      deadline: ticket.deadline,
+    }))),
+    capabilities: copy(state.capabilities),
+  }))
+
+  const acquireLease = async ({ capabilities: rawCapabilities, owner, ttlMs, waitMs }: { capabilities: readonly Capability[]; owner: LeaseOwner; ttlMs: number; waitMs: number }): Promise<MaintenanceLease> => {
+    if (!Number.isFinite(ttlMs) || ttlMs < MIN_TTL_MS || ttlMs > MAX_TTL_MS || !Number.isFinite(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS || waitMs > ttlMs)
+      fail('maintenance_invalid', 'maintenance ttl/wait is outside the finite bounds')
+    if (identityState(owner) !== 'live') fail('maintenance_invalid', 'maintenance lease owner identity is not exact and live')
+    const capabilities = canonicalCapabilities(rawCapabilities)
+    const token = input.randomBytes(32).toString('hex')
+    const started = locked((state, dirty) => {
+      if (state.state !== 'open') fail('maintenance_conflict', `session maintenance is already ${state.state}`, { state: state.state, epoch: state.epoch })
+      state.state = 'draining'
+      state.epoch += 1
+      state.tokenHash = hashToken(token)
+      state.owner = copy(owner)
+      state.heartbeatDeadline = input.now() + ttlMs
+      state.capabilities = capabilities.map((capability) => ({ capability, state: 'unused' }))
+      state.delegates = []
+      if (state.tickets.length === 0) state.state = 'active'
+      dirty()
+      return {
+        token,
+        epoch: state.epoch,
+        state: state.state as MaintenanceLease['state'],
+        owner: copy(owner),
+        capabilities: copy(capabilities),
+      }
+    })
+    input.onEvent?.({ type: 'maintenance-acquire', state: started.state, epoch: started.epoch })
+    if (started.state === 'active' || waitMs === 0) return started
+    const deadline = input.now() + waitMs
+    for (;;) {
+      const current = readState()
+      if (current.epoch !== started.epoch || current.state === 'open') fail('maintenance_conflict', 'maintenance acquisition lost its epoch')
+      if (current.state === 'active') return { ...started, state: 'active' }
+      if (input.now() >= deadline) return started
+      await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+  }
+
+  const heartbeatLease = async ({ token, epoch, ttlMs }: { token: string; epoch: number; ttlMs: number }): Promise<void> => {
+    if (!Number.isFinite(ttlMs) || ttlMs < MIN_TTL_MS || ttlMs > MAX_TTL_MS) fail('maintenance_invalid', 'maintenance heartbeat ttl is outside the finite bounds')
+    locked((state, dirty) => {
+      if (state.epoch !== epoch || (state.state !== 'active' && state.state !== 'draining')) fail('maintenance_conflict', 'maintenance heartbeat names a stale epoch', { state: state.state, epoch: state.epoch })
+      if (!presentedTokenMatches(token, state.tokenHash)) fail('maintenance_token_invalid', 'maintenance bearer is missing, wrong, or stale', { state: state.state, epoch: state.epoch })
+      state.heartbeatDeadline = input.now() + ttlMs
+      dirty()
+    })
+    input.onEvent?.({ type: 'maintenance-heartbeat', epoch })
+  }
+
+  const releaseLease = async ({ token, epoch }: { token: string; epoch: number }): Promise<void> => {
+    locked((state, dirty) => {
+      if (state.epoch !== epoch || state.state === 'open') fail('maintenance_conflict', 'maintenance release names a stale epoch', { state: state.state, epoch: state.epoch })
+      if (!presentedTokenMatches(token, state.tokenHash)) fail('maintenance_token_invalid', 'maintenance bearer is missing, wrong, or stale', { state: state.state, epoch: state.epoch })
+      if (state.tickets.length) fail('maintenance_tickets_live', 'maintenance cannot release while exact live or ambiguous tickets remain', { state: state.state, epoch: state.epoch })
+      state.state = 'open'
+      state.tokenHash = null
+      state.owner = null
+      state.heartbeatDeadline = null
+      state.capabilities = []
+      state.delegates = []
+      dirty()
+    })
+    input.onEvent?.({ type: 'maintenance-release', epoch })
+  }
+
+  const runOperation = async <T>(operation: Operation, body: (ticket: MaintenanceTicket) => Promise<T> | T): Promise<T> => {
+    const owner = input.selfIdentity()
+    const ticket = beginOperationTicket(operation, owner)
+    let outcome: 'committed' | 'retryable' | 'indeterminate' = 'indeterminate'
+    try {
+      const result = await context.run({ ticketId: ticket.id }, () => body({
+        id: ticket.id,
+        epoch: ticket.epoch,
+        delegateSharedSpawn: (sessionId: string) => delegateForTicket(ticket.id, sessionId),
+      }))
+      outcome = (operation.op === 'stop' || operation.op === 'resume')
+        && (result === false || (!!result && typeof result === 'object' && 'ok' in result && (result as { ok?: unknown }).ok === false))
+        ? 'retryable'
+        : 'committed'
+      return result
+    } finally {
+      finishTicket(ticket.id, outcome)
+    }
+  }
+
+  const runOperationSync = <T>(operation: Operation, body: (ticket: MaintenanceTicket) => T): T => {
+    const owner = input.selfIdentity()
+    const ticket = beginOperationTicket(operation, owner)
+    let outcome: 'committed' | 'retryable' | 'indeterminate' = 'indeterminate'
+    try {
+      const result = context.run({ ticketId: ticket.id }, () => body({
+        id: ticket.id,
+        epoch: ticket.epoch,
+        delegateSharedSpawn: (sessionId: string) => delegateForTicket(ticket.id, sessionId),
+      }))
+      outcome = (operation.op === 'stop' || operation.op === 'resume')
+        && (result === false || (!!result && typeof result === 'object' && 'ok' in result && (result as { ok?: unknown }).ok === false))
+        ? 'retryable'
+        : 'committed'
+      return result
+    } finally {
+      finishTicket(ticket.id, outcome)
+    }
+  }
+
+  const authorizeHttpOperation = async ({ authenticated, projectMatches, headers, operation }: { authenticated: boolean; projectMatches: boolean; headers: Record<string, string>; operation: Operation }): Promise<Authorization | undefined> => {
+    if (!authenticated) fail('unauthorized', 'authentication is required before maintenance admission')
+    if (!projectMatches) fail('project_mismatch', 'request project does not match the maintenance project')
+    const token = Object.entries(headers).find(([name]) => name.toLowerCase() === 'x-spexcode-session-maintenance')?.[1] ?? ''
+    return locked((state) => {
+      if (!token) {
+        if (state.state === 'active') fail('maintenance_token_invalid', 'maintenance bearer is missing, wrong, or stale', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operationSession(operation) })
+        return undefined
+      }
+      if (state.state !== 'active') fail('maintenance_conflict', 'maintenance lease is not active', { state: state.state, epoch: state.epoch })
+      if (!presentedTokenMatches(token, state.tokenHash)) fail('maintenance_token_invalid', 'maintenance bearer is missing, wrong, or stale', { state: state.state, epoch: state.epoch })
+      const entry = capabilityFor(state, operation)
+      if (!entry) return fail('maintenance_capability_missing', 'operation is not in the exact maintenance capability plan', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operationSession(operation) })
+      if (entry.state !== 'unused') fail('maintenance_capability_used', 'maintenance capability is already inflight, committed, or indeterminate', { state: state.state, epoch: state.epoch, operation: operation.op, sessionId: operationSession(operation) })
+      return { token, epoch: state.epoch }
+    })
+  }
+
+  const beginExternalOperation = (operation: Operation, owner: ProcessIdentity): string => {
+    if (identityState(owner) !== 'live') fail('maintenance_invalid', 'external operation owner is not exact and live')
+    return beginOperationTicket(operation, owner).id
+  }
+  const finishExternalOperation = (ticketId: string, owner: ProcessIdentity): void => locked((state, dirty) => {
+    const index = state.tickets.findIndex((ticket) => ticket.id === ticketId && sameIdentity(ticket.owner, owner))
+    if (index < 0) return
+    state.tickets.splice(index, 1)
+    dirty()
+  })
+
+  return {
+    headerName: 'X-SpexCode-Session-Maintenance',
+    runOperation, runOperationSync, acquireLease, heartbeatLease, releaseLease, readState, authorizeHttpOperation,
+    beginExternalOperation, finishExternalOperation,
+  }
+}
+
+function productionProcessIdentity(pid: number): ProcessReading {
+  try { process.kill(pid, 0) } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return null
+    return 'ambiguous'
+  }
+  const startToken = processStartToken(pid)
+  return startToken ? { pid, startToken } : 'ambiguous'
+}
+
+export function exactProcessIdentity(pid: number): ProcessIdentity | null {
+  const reading = productionProcessIdentity(pid)
+  return reading && reading !== 'ambiguous' ? reading : null
+}
+
+const coordinators = new Map<string, ReturnType<typeof createSessionMaintenance>>()
+export function sessionMaintenance(root = projectRuntimeRoot()): ReturnType<typeof createSessionMaintenance> {
+  let coordinator = coordinators.get(root)
+  if (coordinator) return coordinator
+  const detectedStart = processStartToken(process.pid)
+  if (!detectedStart) throw new SessionMaintenanceError('maintenance_identity_unknown', `cannot read exact process identity for ${process.pid}`)
+  const selfStart: string = detectedStart
+  coordinator = createSessionMaintenance({
+    runtimeRoot: root,
+    now: () => Date.now(),
+    randomBytes: cryptoRandomBytes,
+    processIdentity: productionProcessIdentity,
+    selfIdentity: () => ({ pid: process.pid, startToken: selfStart }),
+    ticketReportMs: 30_000,
+  })
+  coordinators.set(root, coordinator)
+  return coordinator
+}
+
+export const runSessionOperation = <T>(operation: Operation, body: (ticket: MaintenanceTicket) => Promise<T> | T): Promise<T> =>
+  sessionMaintenance().runOperation(operation, body)
+export const runSessionOperationSync = <T>(operation: Operation, body: (ticket: MaintenanceTicket) => T): T =>
+  sessionMaintenance().runOperationSync(operation, body)
+
+export function maintenanceBrokerDescriptors(): { request: number; response: number; turn: number } | null {
+  const values = (process.env.SPEXCODE_MAINTENANCE_BROKER_FDS || '').split(',').map(Number)
+  if (values.length !== 3 || values.some((fd) => !Number.isInteger(fd) || fd < 3) || new Set(values).size !== 3) return null
+  return { request: values[0], response: values[1], turn: values[2] }
+}
+
+export function maintenanceErrorPayload(error: unknown): Record<string, unknown> | null {
+  if (!(error instanceof SessionMaintenanceError)) return null
+  return {
+    error: error.message,
+    code: error.code,
+    ...(error.state ? { state: error.state } : {}),
+    ...(error.epoch !== undefined ? { epoch: error.epoch } : {}),
+    ...(error.operation ? { operation: error.operation } : {}),
+    ...(error.sessionId ? { sessionId: error.sessionId } : {}),
+  }
+}