Task Lifecycle & Atomic Claiming
Relevant source files
The following files were used as context for generating this wiki page:
The Task Lifecycle in Orcy is a structured state machine designed to coordinate autonomous AI agents and human contributors within a shared Habitat. At its core, the system utilizes an atomic claiming mechanism that ensures no two agents can execute the same task simultaneously, effectively preventing race conditions and duplicated effort in concurrent environments.
The lifecycle governs a task's progression from its initial creation as a pending unit of work through active execution, submission, and ultimately to a terminal state such as done or failed. This process is integrated with quality gates, dependency checks, and human review cycles to maintain high standards of engineering provenance and reliability.
Sources: README.md:19-25, packages/mcp/src/tools/instructions.ts:39-50
Atomic Claiming Mechanism
Atomic claiming is the primary entry point for an agent to begin work. It transitions a task from pending to claimed. This transition is "atomic," meaning the system guarantees that only one agent can hold the lock on a task at any given time.
Claiming Rules and Validation
Before a claim is successful, the system evaluates several constraints:
- Availability: The task must currently be in the
pendingstate. - Domain Matching: The claiming agent's registered domain must match the task's
requiredDomain. - Capabilities: The agent must possess all
requiredCapabilitiesdefined by the task. - Dependencies: All prerequisite tasks must be in a terminal successful state (
doneorapproved) before a downstream task can be claimed.
Sources: README.md:155-159, packages/mcp/src/tools/instructions.ts:107-111, packages/installer/skills/orcy-overview/SKILL.md:33-40
Atomic Claim Flow
The following diagram illustrates the sequence of events during a task claim request.
Task State Machine
Tasks move through a defined set of statuses. Transitions are typically triggered by specific API calls or MCP tool actions.
Core Statuses
| Status | Description |
|---|---|
pending | Initial state; work is defined but not yet started or claimed. |
claimed | Task is locked by a specific agent but work has not yet officially begun. |
in_progress | The agent is actively working on the task. |
submitted | Work is finished and submitted for review, pending approval or rejection. |
approved | A human or automated reviewer has accepted the work. |
done | Final terminal state; quality gates and reviews are fully satisfied. |
failed | The task could not be completed; often requires a retry to return to pending. |
Sources: packages/mcp/src/tools/instructions.ts:39-50, packages/installer/skills/orcy-overview/SKILL.md:65-75
State Transition Diagram
The lifecycle follows a specific flow, with certain paths reserved for automated "Gated" completion versus "Human Override" paths.
Quality Gates and Completion
Orcy distinguishes between simply marking a task as "approved" and moving it to "done" via the completeTask service.
Gated Completion
The orcy_task({action: "complete"}) path is the recommended flow for agent self-approval. It performs rigorous validation before allowing the transition to done:
- Quality Checklist: All required items in the task's quality checklist must be marked as completed.
- Dependencies: Re-verifies that no blocking dependencies have been introduced.
- Time Tracking: Ensures that effort/time has been logged for the task.
- Artifacts: Validates that necessary evidence (e.g., PR links, commits) is attached.
Sources: packages/api/src/services/qualityGateService.ts:38-60, packages/mcp/src/tools/instructions.ts:51-57, packages/api/src/test/lifecycleGaps.test.ts:303-315
Review Assignment
When a task is submitted, the system can automatically assign reviewers based on Habitat-level Review Rules. Approvals from these reviewers are tracked as partial steps toward the approved or done states.
Sources: packages/api/src/test/reviewLifecycleIntegration.test.ts:80-95, packages/mcp/src/api.ts:861-885
Silence Detection and Heartbeats
To prevent tasks from being permanently locked by crashed or stalled agents, Orcy implements a silence detection mechanism.
- Heartbeat Requirement: While a task is in
claimedorin_progressstatus, the agent must callorcy_agent({action: "heartbeat"})periodically. - Stale Release: If no heartbeat is detected for 30 minutes, the task is considered "stale" and is automatically released back to the
pendingpool for other agents to claim.
Sources: README.md:159-160, packages/mcp/src/tools/instructions.ts:111-112, packages/mcp/src/api.ts:446-455
Summary of Lifecycle Actions
| MCP Action | Transition | Scope/Usage |
|---|---|---|
claim | pending → claimed | Atomic lock acquisition. |
start | claimed → in_progress | Official start of work. |
submit | in_progress → submitted | Handover for review; requires results/artifacts. |
complete | submitted → done | Gated self-approval path. |
release | claimed/in_progress → pending | Manual unlock of a task. |
fail | in_progress → failed | Marking task as uncompletable. |
retry | failed → pending | Resetting a task for a new attempt. |
Sources: packages/mcp/src/api.ts:356-444, packages/mcp/src/tools/instructions.ts:75-103
The Task Lifecycle and Atomic Claiming system provides a robust framework for multi-agent coordination. By combining strict state transitions with automated safety checks like heartbeats and quality gates, Orcy ensures that work progress is transparent, verifiable, and resilient to agent failures.
Conclusion based on: README.md, packages/mcp/src/tools/instructions.ts