> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
graph TD
    P[pending] -->|start| IP[in_progress]
    IP -->|complete| C[completed]
    IP -->|fail| F[failed]
    IP -->|block| B[blocked]
    B -->|unblock| IP2[in_progress]
    IP2 -->|complete| C2[completed]
```

## 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:

<Steps>
  <Step title="User Clicks Play">
    The user clicks the play button on a pending task in the dashboard. This triggers:

    1. `POST /api/tasks/:id/start` -- Updates status to `in_progress`
    2. A chat message is sent to the gateway: "Work on task: \[title]"
  </Step>

  <Step title="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>

  <Step title="Agent Completes">
    When finished, the agent:

    1. Calls the `tasks` tool with `action: complete`
    2. Emits `[TASK_DONE:title]` in the response stream
  </Step>

  <Step title="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
  </Step>
</Steps>

## Heartbeat-Triggered Tasks

The [heartbeat system](/gateway/heartbeat) can trigger task work autonomously:

<Steps>
  <Step title="Heartbeat fires on schedule" />

  <Step title="Agent checks for pending tasks" />

  <Step title="Picks the highest-priority task" />

  <Step title="Works on it and updates status" />
</Steps>

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

## 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

```bash theme={null}
# Complete all tasks matching a filter
argent tasks complete --status in_progress --older-than 7d

# List overdue tasks
argent tasks list --overdue
```