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.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { AGENT_STATUS_STALE_AFTER_MS } from './agent-status-types'
import type { FleetAgentStatusEvidence } from './orchestration-fleet-agent-status-evidence'
import { projectOrchestrationFleetAttention } from './orchestration-fleet-attention'
import {
isUnsupervisedSettledDispatch,
resolveFleetWorkerOutcome
} from './orchestration-fleet-outcome-resolution'
import { readWorkerTerminalHostScope } from './worker-terminal-host-scope'
import type {
FleetDurableWorker,
FleetLiveness,
FleetNextAction,
FleetResourceProjection,
OrchestrationFleetWorker
} from './orchestration-fleet-projection'
const FLEET_STATUS_FUTURE_TOLERANCE_MS = 5_000
/** Everything the liveness verdict reads, so every surface can share one projection. */
type FleetLivenessSubject = {
workerStage?: string | null
workerState?: string | null
dispatchStatus?: string | null
terminationReason?: FleetDurableWorker['terminationReason']
resource: { releaseState?: string | null; hostScope: string | null } | null
}
/** Durable facts that prove a supervised process ended; the removed-work record reads the same proof. */
export const DURABLE_EXIT_PROOF = {
workerState: 'stopped',
workerStage: 'released',
resourceReleaseState: 'released',
terminationReasons: ['operator_close', 'signaled', 'exited']
} as const satisfies {
workerState: string
workerStage: string
resourceReleaseState: string
terminationReasons: readonly NonNullable<FleetDurableWorker['terminationReason']>[]
}
/** Worker states that carry an outcome; anything else is still supposed to be running. */
const SETTLED_WORKER_STATES = new Set(['succeeded', 'failed', 'stopped', 'abandoned'])
/** Any certified termination reason proves exit independently of settlement state. */
function hasCertifiedExit(worker: FleetLivenessSubject): boolean {
return (
// unknown means stop without observed exit; null is pre-v29, when the stage alone recorded exit.
(worker.workerStage === 'process_exited' && worker.terminationReason !== 'unknown') ||
DURABLE_EXIT_PROOF.terminationReasons.some((reason) => reason === worker.terminationReason)
)
}
export function projectLiveness(
worker: FleetLivenessSubject,
evidence: FleetAgentStatusEvidence | undefined,
now: number
): FleetLiveness {
// Federated release proves terminal exit, independently of the worker outcome.
if (worker.workerStage === DURABLE_EXIT_PROOF.workerStage) {
return { verdict: 'exited', source: 'execution_host' }
}
if (worker.resource?.releaseState === DURABLE_EXIT_PROOF.resourceReleaseState) {
return { verdict: 'exited', source: 'resource_release' }
}
if (worker.workerState === DURABLE_EXIT_PROOF.workerState) {
return { verdict: 'exited', source: 'worker_stop' }
}
// Operator-close settlement also proves exit; it must not fall through to missing_status.
if (hasCertifiedExit(worker)) {
return { verdict: 'exited', source: 'execution_host' }
}
// Settled unsupervised dispatches have no process to miss, but absence still cannot certify exit.
if (!evidence && isUnsupervisedSettledDispatch(worker)) {
return { verdict: 'unverifiable', reason: 'unsupervised_settled' }
}
if (!evidence) {
return { verdict: 'unverifiable', reason: 'missing_status' }
}
// Require explicit delivery-clock arms for old hosts; missing producer timestamps cannot masquerade as compatibility.
const observedAt = evidence.clock.at
const activity = evidence.activity
if (activity.restoredUnconfirmed) {
return { verdict: 'unverifiable', reason: 'restored_unconfirmed', observedAt }
}
if (activity.providerSessionOnly) {
return { verdict: 'unverifiable', reason: 'missing_status', observedAt }
}
if (observedAt - now > FLEET_STATUS_FUTURE_TOLERANCE_MS) {
return { verdict: 'unverifiable', reason: 'future_status', observedAt }
}
const remoteHost =
projectHost(activity.connectionId, worker.resource?.hostScope).kind === 'remote'
if (remoteHost && !activity.connectionId) {
return { verdict: 'unverifiable', reason: 'missing_status', observedAt }
}
if (now - observedAt > AGENT_STATUS_STALE_AFTER_MS) {
return { verdict: 'unverifiable', reason: 'stale_status', observedAt }
}
return { verdict: 'live', observedAt, source: 'agent_status' }
}
function projectResource(worker: FleetDurableWorker): FleetResourceProjection {
const resource = worker.resource
if (!resource) {
return {
state: 'absent',
reason: worker.workerState === 'unsupervised' ? 'unsupervised' : 'not_materialized'
}
}
const state = ['owned', 'transferred', 'user_owned', 'external', 'released'].includes(
resource.ownershipState
)
? (resource.ownershipState as Exclude<FleetResourceProjection['state'], 'absent'>)
: 'external'
return {
state,
id: resource.id,
ownerDispatchId: resource.ownerDispatchId,
releaseState: resource.releaseState,
terminalState: worker.terminalState
}
}
/** Recompute after host verdicts; stale local inspect must not outrank recover for proven remote exit. */
export function projectFleetNextAction(
worker: FleetDurableWorker,
liveness: FleetLiveness
): FleetNextAction {
if (worker.workerStage === 'released') {
return { kind: 'none', argv: [] }
}
if (worker.terminalState === 'reclaimable') {
return {
kind: 'release',
argv: ['orchestration', 'worker-release', '--dispatch', worker.dispatchId]
}
}
// Legacy settled dispatches with no resource/worker have nothing to release; inspect would loop.
if (
worker.terminalState === 'released' ||
(worker.dispatchStatus === 'completed' &&
(!worker.agentTerminalHandle || (isUnsupervisedSettledDispatch(worker) && !worker.resource)))
) {
return { kind: 'none', argv: [] }
}
// Settled workers still owning terminals need release; worker-show would repeat the settlement.
if (SETTLED_WORKER_STATES.has(worker.workerState) && worker.resource) {
return worker.resource.ownershipState === 'owned' && worker.resource.releaseState !== 'released'
? {
kind: 'release',
argv: ['orchestration', 'worker-release', '--dispatch', worker.dispatchId]
}
: { kind: 'none', argv: [] }
}
// Unsettled workers with proven exits need transcript recovery, then stop/abandon; unverifiable absence cannot qualify.
if (
liveness.verdict === 'exited' &&
!SETTLED_WORKER_STATES.has(worker.workerState) &&
!worker.pendingInput &&
!worker.pendingApproval
) {
return {
kind: 'recover',
argv: ['orchestration', 'worker-read', '--dispatch', worker.dispatchId]
}
}
// Live workers with no pending input owe no action; inspect would repeat this projection.
if (
liveness.verdict === 'live' &&
worker.workerState === 'ready' &&
!worker.pendingInput &&
!worker.pendingApproval
) {
return { kind: 'none', argv: [] }
}
// worker-show repeats this projection; absence alone cannot earn another command.
if (liveness.verdict === 'unverifiable' && !worker.pendingInput && !worker.pendingApproval) {
return { kind: 'none', argv: [] }
}
return {
kind: 'inspect',
argv: ['orchestration', 'worker-show', '--dispatch', worker.dispatchId]
}
}
function projectHost(
connectionId: string | null,
hostScope: string | null | undefined
): OrchestrationFleetWorker['host'] {
if (connectionId) {
return { kind: 'remote', id: connectionId }
}
const read = readWorkerTerminalHostScope(hostScope)
switch (read.kind) {
// Absent host scope is legacy local/folder authority; resource materialization alone cannot imply remote execution.
case 'absent':
return { kind: 'local', id: 'local' }
case 'local':
return { kind: 'local', id: read.id }
case 'remote':
return { kind: 'remote', id: read.id }
case 'unreadable':
return { kind: 'remote', id: 'unknown' }
}
}
export function projectOrchestrationFleetWorker(
worker: FleetDurableWorker,
evidence: FleetAgentStatusEvidence | undefined,
now: number
): OrchestrationFleetWorker {
const liveness = projectLiveness(worker, evidence, now)
const fresh = liveness.verdict === 'live'
const activity = evidence?.activity
const workspaceId =
activity?.worktreeId ?? worker.worktreeId ?? worker.resource?.worktreeId ?? null
const outcome = resolveFleetWorkerOutcome({
attemptOutcome: worker.outcome,
workerState: worker.workerState,
dispatchStatus: worker.dispatchStatus
})
return {
id: worker.dispatchId,
dispatchId: worker.dispatchId,
taskId: worker.taskId,
runId: worker.runId,
role: 'worker',
parent: worker.parentTaskId ? { taskId: worker.parentTaskId } : null,
provider: activity?.agentType ? { id: activity.agentType, model: activity.model } : null,
host: projectHost(activity?.connectionId ?? null, worker.resource?.hostScope),
workspace: workspaceId ? { id: workspaceId, kind: 'folder_or_worktree' } : null,
stage: {
worker: worker.workerState,
dispatch: worker.dispatchStatus,
detail: worker.workerStage,
activity: fresh && activity ? activity.state : 'unknown'
},
outcome,
liveness,
evidence: {
durable: true,
liveStatus: !evidence
? 'unavailable'
: evidence.activity.restoredUnconfirmed
? 'redacted_restore'
: fresh
? 'fresh'
: 'stale',
lastObservedAt: evidence ? evidence.clock.at : null
},
resource: projectResource(worker),
nextAction: projectFleetNextAction(worker, liveness),
attention: projectOrchestrationFleetAttention({
isRoot: worker.parentTaskId === null,
outcome,
pendingInput: worker.pendingInput,
pendingApproval: worker.pendingApproval,
interrupted:
worker.workerState === 'abandoned' ||
worker.terminationReason === 'operator_close' ||
worker.terminationReason === 'signaled',
liveness
})
}
}