Task Lifecycle

The full task flow — pending to in_progress to completed, with dashboard integration.

Overview

Every task follows a lifecycle from creation through completion (or failure). The lifecycle is designed for accountability -- you can see what the agent is working on, what is blocked, and what has been accomplished.

Status Flow

                 ┌──────────┐
                 │  pending  │
                 └─────┬─────┘
                       │ start
                       v
                 ┌──────────────┐
            ┌────│ in_progress  │────┐
            │    └──────────────┘    │
            │ block           complete│ fail
            v                        v
      ┌──────────┐          ┌─────────────┐
      │ blocked  │          │  completed  │
      └────┬─────┘          └─────────────┘
           │ unblock                │
           v                 ┌──────────┐
     ┌──────────────┐       │  failed   │
     │ in_progress  │       └──────────┘
     └──────────────┘

Status Definitions

Status	Description	Who Sets It
`pending`	Task created, waiting to be started	System (on creation)
`in_progress`	Agent is actively working	User (play button) or agent
`completed`	Task finished successfully	Agent (`tasks_complete`)
`failed`	Task could not be completed	Agent (with error reason)
`blocked`	Waiting on external dependency	Agent (`tasks_block`)

The Dashboard Play Flow

This is the primary task execution workflow:

Step 1: User Clicks Play

The user clicks the play button on a pending task in the dashboard. This triggers:

POST /api/tasks/:id/start -- Updates status to in_progress
A chat message is sent to the gateway: "Work on task: [title]"

Step 2: Agent Receives and Works

The agent receives the message and begins working. It can:

Use any available tools (exec, browser, memory, etc.)
Stream progress updates in the chat
Create sub-tasks if needed

Step 3: Agent Completes

When finished, the agent:

Calls the tasks tool with action: complete
Emits [TASK_DONE:title] in the response stream

Step 4: Dashboard Updates

The dashboard updates through two mechanisms:

Instant: Parses [TASK_DONE:title] from the stream for immediate UI update
Polling: Checks the database every 5 seconds as a backup

Heartbeat-Triggered Tasks

The heartbeat system can trigger task work autonomously:

Heartbeat fires on schedule
Agent checks for pending tasks
Picks the highest-priority task
Works on it and updates status

This enables the agent to work on tasks even when no user is actively chatting.

Task Accountability

Tasks track:

Who created it: User, agent, heartbeat, or schedule
When each status change happened: Full audit trail
Time spent: Duration in each status
Completion notes: What the agent did to complete the task

Bulk Operations

# Complete all tasks matching a filter
argent tasks complete --status in_progress --older-than 7d

# List overdue tasks
argent tasks list --overdue

On this page