Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

12.3 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import {
  adjudicateAgentSessionRestart,
  agentSessionLeaseAdmitsWriter,
  evaluateAgentSessionAcquisition,
  isProvenAliveProbe,
  isProvenDeadProbe,
  type AgentSessionOwnerProbe
} from './agent-session-lease-adjudication'
import { normalizeLegacyHandoffLease } from './agent-session-legacy-handoff-lease'
import type { AgentSessionLease } from './agent-session-record'

const OWNER = {
  hostId: 'local',
  pid: 4242,
  processStartTimeMs: 1_700_000_000_000,
  spawnToken: 'spawn-a'
}

function lease(overrides: Partial<AgentSessionLease> = {}): AgentSessionLease {
  return {
    sessionId: 'session-alpha-1',
    runtimeKind: 'native',
    runtimeFence: 7,
    handoffStage: null,
    provenHandleLinkId: 'link-1',
    ownerProcess: OWNER,
    reservedSpawnToken: 'spawn-a',
    leaseDeadlineAt: 1_000,
    lastRenewedAt: 500,
    handoffOperationId: null,
    claimKeyId: 'key-1',
    claimStatus: 'live',
    unreconciled: false,
    deathEvidence: null,
    ...overrides
  }
}

const MATCHED: AgentSessionOwnerProbe = { outcome: 'identity-matched', matchedOn: ['spawn-token'] }
const INDETERMINATE: AgentSessionOwnerProbe = { outcome: 'indeterminate', reason: 'no answer' }

function acquire(
  leaseState: AgentSessionLease,
  probe: AgentSessionOwnerProbe,
  handoffOperationId: string | null = null
) {
  return evaluateAgentSessionAcquisition({
    lease: leaseState,
    expectedFence: leaseState.runtimeFence,
    handoffOperationId,
    probe
  })
}

describe('proof classification', () => {
  it('treats a pid match with nothing PID-reuse-safe as no proof at all', () => {
    // A bare pid match is exactly the case that mints a second writer after pid reuse.
    expect(isProvenAliveProbe({ outcome: 'identity-matched', matchedOn: [] })).toBe(false)
    expect(isProvenAliveProbe(MATCHED)).toBe(true)
    expect(isProvenDeadProbe(INDETERMINATE)).toBe(false)
    expect(isProvenAliveProbe(INDETERMINATE)).toBe(false)
  })

  it.each([
    ['exit-observed', { outcome: 'exit-observed' } as AgentSessionOwnerProbe],
    ['pid-absent', { outcome: 'pid-absent' } as AgentSessionOwnerProbe],
    [
      'identity-mismatch',
      { outcome: 'identity-mismatch', field: 'spawn-token' } as AgentSessionOwnerProbe
    ]
  ])('accepts %s as proof of death', (_name, probe) => {
    expect(isProvenDeadProbe(probe)).toBe(true)
  })

  it('never counts a reservation probe or an indeterminate answer as death', () => {
    expect(isProvenDeadProbe({ outcome: 'reservation-unused' })).toBe(false)
    expect(isProvenDeadProbe(INDETERMINATE)).toBe(false)
  })
})

describe('acquisition compare-and-swap', () => {
  it('refuses a stale fence and grants at exactly fence + 1', () => {
    const held = lease({ ownerProcess: null, claimStatus: 'released', reservedSpawnToken: null })
    expect(
      evaluateAgentSessionAcquisition({
        lease: held,
        expectedFence: held.runtimeFence - 1,
        handoffOperationId: null,
        probe: MATCHED
      })
    ).toEqual({
      decision: 'refused',
      code: 'agent_session_checkpoint_stale',
      details: { reason: 'fenceStale' }
    })
    expect(acquire(held, MATCHED)).toEqual({ decision: 'granted', nextFence: 8 })
  })

  it('refuses a cached fence after the lease advances to a reservation', () => {
    const before = lease({ ownerProcess: null, claimStatus: 'released', reservedSpawnToken: null })
    const winner = acquire(before, MATCHED)
    expect(winner).toEqual({ decision: 'granted', nextFence: 8 })
    // The loser still holds the pre-swap fence, which is no longer current.
    const after = lease({ ...before, runtimeFence: 8, claimStatus: 'reserved' })
    expect(
      evaluateAgentSessionAcquisition({
        lease: after,
        expectedFence: 7,
        handoffOperationId: null,
        probe: MATCHED
      })
    ).toEqual({
      decision: 'refused',
      code: 'agent_session_checkpoint_stale',
      details: { reason: 'fenceStale' }
    })
  })

  it('never grants a second owner on expiry alone', () => {
    // The recorded owner is long past its deadline; nothing here may consult that deadline.
    const expired = lease({ leaseDeadlineAt: 1, lastRenewedAt: 1 })
    expect(acquire(expired, INDETERMINATE)).toEqual({
      decision: 'refused',
      code: 'agent_session_ownership_unknown',
      details: { reason: 'ownerUnproven' }
    })
    expect(acquire(expired, MATCHED)).toEqual({
      decision: 'refused',
      code: 'agent_session_conflict',
      details: { reason: 'ownerAlive' }
    })
    expect(acquire(expired, { outcome: 'pid-absent' })).toEqual({
      decision: 'granted',
      nextFence: 8
    })
  })

  it('refuses while unreconciled even with proof the owner is dead', () => {
    expect(acquire(lease({ unreconciled: true }), { outcome: 'pid-absent' })).toEqual({
      decision: 'refused',
      code: 'execution_owner_reconciling',
      details: { reason: 'hostReconciling' }
    })
  })

  it('keeps a conflicted claim conflicted regardless of proof', () => {
    // Restart adjudication and recovery resolution are what retire it, once its owner is gone.
    expect(acquire(lease({ claimStatus: 'conflicted' }), { outcome: 'exit-observed' })).toEqual({
      decision: 'refused',
      code: 'agent_session_conflict',
      details: { reason: 'claimConflicted' }
    })
  })

  it('refuses acquisition in the recovering stage', () => {
    expect(acquire(lease({ handoffStage: 'recovering' }), { outcome: 'pid-absent' })).toEqual({
      decision: 'refused',
      code: 'agent_session_ownership_unknown',
      details: { reason: 'ownerUnproven' }
    })
  })

  it('refuses a different acquisition operation and replays the matching one', () => {
    const mid = lease({
      handoffStage: 'new-owner-proving',
      handoffOperationId: 'op-1',
      ownerProcess: null,
      claimStatus: 'reserved'
    })
    expect(acquire(mid, { outcome: 'reservation-unused' }, 'op-2')).toEqual({
      decision: 'refused',
      code: 'agent_session_operation_conflict',
      details: { reason: 'handoffInFlight' }
    })
    expect(acquire(mid, { outcome: 'reservation-unused' }, 'op-1')).toEqual({
      decision: 'retry-reservation',
      fence: 7
    })
  })

  it('refuses a reservation whose spawn may have won the race with the crash', () => {
    const reserved = lease({ ownerProcess: null, claimStatus: 'reserved', handoffStage: null })
    expect(acquire(reserved, INDETERMINATE)).toEqual({
      decision: 'refused',
      code: 'agent_session_ownership_unknown',
      details: { reason: 'ownerUnproven' }
    })
    expect(acquire(reserved, { outcome: 'reservation-unused' })).toEqual({
      decision: 'granted',
      nextFence: 8
    })
  })
})

describe('restart reconciliation', () => {
  it('keeps a surviving terminal owner an older build recorded conflicted; nothing re-adopts it', () => {
    const normalized = normalizeLegacyHandoffLease({ ...lease(), runtimeKind: 'tui' })
    expect(normalized).toMatchObject({ runtimeKind: 'native', claimStatus: 'conflicted' })
    expect(
      adjudicateAgentSessionRestart({
        lease: normalized,
        probe: MATCHED,
        observedAt: 9_000
      })
    ).toMatchObject({ disposition: 'recovering', stage: 'recovering' })
  })

  it('routes a surviving native owner to recovery instead of readopting a dead transport', () => {
    // The runtime crash lost native stdio; stop the orphan and respawn at fence + 1 instead of readopting an undrivable child.
    expect(
      adjudicateAgentSessionRestart({ lease: lease(), probe: MATCHED, observedAt: 9_000 })
    ).toMatchObject({ disposition: 'recovering', stage: 'recovering' })
  })

  it('bumps the fence exactly once for a proven-dead owner and records the evidence', () => {
    const result = adjudicateAgentSessionRestart({
      lease: lease(),
      probe: { outcome: 'identity-mismatch', field: 'process-start-time' },
      observedAt: 9_000
    })
    expect(result).toEqual({
      disposition: 'evicted',
      nextFence: 8,
      // The death happened between the last renewal and the probe.
      evidence: {
        kind: 'identity-mismatch',
        detail: 'mismatched process-start-time',
        observedAt: 9_000,
        ownerFence: 7,
        lastProvenAliveAt: 500
      }
    })
  })

  it('never records the owner alive after the probe that found it gone', () => {
    // A clock stepped back across the restart would otherwise write an interval load rejects.
    expect(
      adjudicateAgentSessionRestart({
        lease: lease({ lastRenewedAt: 9_500 }),
        probe: { outcome: 'pid-absent' },
        observedAt: 9_000
      })
    ).toMatchObject({ evidence: { observedAt: 9_000, lastProvenAliveAt: 9_000 } })
  })

  it('hands an unverifiable owner to recovery resolution instead of evicting it', () => {
    expect(
      adjudicateAgentSessionRestart({
        lease: lease({ leaseDeadlineAt: 1 }),
        probe: INDETERMINATE,
        observedAt: 9_000
      })
    ).toEqual({ disposition: 'recovering', stage: 'recovering', reason: 'no answer' })
  })

  it('re-adjudicates a claim an older record marked conflicted by the owner it names', () => {
    expect(
      adjudicateAgentSessionRestart({
        lease: lease({ claimStatus: 'conflicted' }),
        probe: INDETERMINATE,
        observedAt: 9_000
      })
    ).toEqual({ disposition: 'recovering', stage: 'recovering', reason: 'no answer' })
    expect(
      adjudicateAgentSessionRestart({
        lease: lease({ claimStatus: 'conflicted', ownerProcess: null }),
        probe: INDETERMINATE,
        observedAt: 9_000
      })
    ).toEqual({ disposition: 'evicted', nextFence: 8, evidence: null })
  })

  it('frees a conflict whose named owner is proven gone', () => {
    // Once this specific process is proven gone, retain no conflict that would permanently prevent reopening.
    expect(
      adjudicateAgentSessionRestart({
        lease: lease({ claimStatus: 'conflicted' }),
        probe: { outcome: 'pid-absent' },
        observedAt: 9_000
      })
    ).toEqual({
      disposition: 'evicted',
      nextFence: 8,
      evidence: {
        kind: 'pid-absent',
        detail: 'recorded pid absent on host',
        observedAt: 9_000,
        ownerFence: 7,
        lastProvenAliveAt: 500
      }
    })
  })

  it('frees a lease that names neither an owner nor a reservation, without moving the fence', () => {
    // Evicted leases have neither owner nor token to probe; treating them as unproven reservations re-latches every released record.
    expect(
      adjudicateAgentSessionRestart({
        lease: lease({
          ownerProcess: null,
          reservedSpawnToken: null,
          claimStatus: 'released',
          handoffStage: 'recovering'
        }),
        probe: INDETERMINATE,
        observedAt: 9_000
      })
    ).toEqual({ disposition: 'free', reason: 'lease has no owner and no reservation' })
  })

  it.each([null, 'recovering'] as const)(
    'releases an ownerless reservation at stage %s, with evidence only when a scan proved nothing spawned',
    (handoffStage) => {
      // Before identity is saved, a crashed child loses stdio and only a token scan can prove absence.
      const reserved = lease({ ownerProcess: null, claimStatus: 'reserved', handoffStage })
      expect(
        adjudicateAgentSessionRestart({ lease: reserved, probe: INDETERMINATE, observedAt: 9_000 })
      ).toEqual({ disposition: 'evicted', nextFence: 8, evidence: null })
      expect(
        adjudicateAgentSessionRestart({
          lease: reserved,
          probe: { outcome: 'reservation-unused' },
          observedAt: 9_000
        })
      ).toEqual({
        disposition: 'evicted',
        nextFence: 8,
        // The proof is about this reservation's own fence.
        evidence: {
          kind: 'pid-absent',
          detail: 'reservation never spawned',
          observedAt: 9_000,
          ownerFence: 7
        }
      })
    }
  )
})

describe('writer admission', () => {
  it('admits a writer only when reconciled, settled, live, and holding a process', () => {
    expect(agentSessionLeaseAdmitsWriter(lease())).toBe(true)
    expect(agentSessionLeaseAdmitsWriter(lease({ unreconciled: true }))).toBe(false)
    expect(agentSessionLeaseAdmitsWriter(lease({ handoffStage: 'new-owner-proving' }))).toBe(false)
    expect(agentSessionLeaseAdmitsWriter(lease({ claimStatus: 'reserved' }))).toBe(false)
    expect(agentSessionLeaseAdmitsWriter(lease({ ownerProcess: null }))).toBe(false)
  })
})