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

# Tasks

> The shared work queue — claimable units of work in a team inbox or a personal one, with leases instead of assignments

# Draft — needs review

## What a task is

A **task** is one claimable unit of work sitting in a team's inbox or a person's. It carries a `title`, an optional markdown `body`, an optional `kind` (a slug a mounted skill declares it handles), and a producer-defined `payload` of ids and refs.

Tasks come from three places: [sources](/concepts/sources) landing what they discovered, humans filing work by hand, and skills filing follow-ups for each other.

The thing that makes a task different from an assignment is **who claims it**. Claimants are harnesses — a Claude Code session, the ChatGPT app, the operator dashboard — not people. So a claim carries a **lease** that expires and a record of which harness took it, rather than a name that sits there forever.

## The lifecycle

```
open ──claim──> claimed ──complete──> done
 │                 │
 │                 └──release / lease lapses──> open
 │
 └──dismiss──> dismissed
```

Both closed states are reopenable. Nothing about a task is destructive.

| Verb       | What it does                                                       |
| ---------- | ------------------------------------------------------------------ |
| `claim`    | Take the task and hold a lease. Re-claiming your own extends it    |
| `touch`    | Extend the lease you hold. Forward-only — it can never shorten one |
| `release`  | Give the claim back. A team owner may release anyone's claim       |
| `complete` | Close it and attach results                                        |
| `dismiss`  | Close it without doing it, with an optional reason                 |
| `reopen`   | Bring a `done` or `dismissed` task back to `open`                  |

**Leases** run from 15 minutes to 72 hours, defaulting to 2. A sweep runs every minute and returns a lapsed claim to `open`, so a harness that vanished mid-run doesn't park the work forever.

**Races resolve at the database, not in your code.** Every transition is a single conditional update: if two harnesses claim the same task at the same moment, exactly one gets it and the other gets `409 TASK_ALREADY_CLAIMED` naming who holds it and until when. You never have to check-then-claim.

**Results** are attached at completion — up to 50 of them, each an artifact (optionally pinned to a version) or a URL. Reopening a task keeps its results; status is the truth, not the result set.

## Personal vs team scope

A task belongs to exactly one scope — a team, or a person.

|                    | Team task                         | Personal task                         |
| ------------------ | --------------------------------- | ------------------------------------- |
| Who can see it     | Any current member                | The owner only (others get `404`)     |
| Who can claim it   | Any current member                | — there is no claim protocol          |
| Completing         | Requires holding a live claim     | Straight from `open`, no claim needed |
| Suggested assignee | Advisory — anyone may still claim | —                                     |

`suggested_assignee_id` is a hint, not a lock. It says "this is probably yours" and drives the default `mine` view; it never stops a teammate from picking the work up.

When a member leaves a team, their claims are released and suggestions pointing at them are cleared.

## How agents use it

<CodeGroup>
  ```bash CLI theme={null}
  # What is waiting — personal tasks plus team tasks suggested to or claimed by me
  rip task list

  # Everything in one team
  rip task list --team quintel --status open --kind process-call

  rip task show <id>
  rip task claim <id> --lease-hours 4
  rip task done <id> --result artifact:fathom-98213@2
  rip task timeline <id>

  # File work for someone else
  rip task add "Review pricing copy" --team quintel --assignee alek --kind write-post
  ```

  ```json MCP theme={null}
  task_list   { "team": "quintel", "status": "open", "kind": "process-call" }
  task_get    { "id": "<uuid>" }
  task_create { "team": "quintel", "title": "…", "kind": "process-call", "payload": {} }
  task_claim  { "id": "<uuid>", "leaseHours": 4 }
  task_touch  { "id": "<uuid>" }
  task_release { "id": "<uuid>" }
  task_complete { "id": "<uuid>", "results": [{ "type": "artifact", "id": "fathom-98213" }] }
  task_dismiss  { "id": "<uuid>", "reason": "duplicate" }
  task_reopen   { "id": "<uuid>" }
  ```

  ```bash REST theme={null}
  GET    /v0/tasks?team=quintel&status=open&kind=process-call
  POST   /v0/tasks
  GET    /v0/tasks/{id}
  POST   /v0/tasks/{id}/claim
  POST   /v0/tasks/{id}/touch
  POST   /v0/tasks/{id}/release
  POST   /v0/tasks/{id}/complete
  POST   /v0/tasks/{id}/dismiss
  POST   /v0/tasks/{id}/reopen
  ```
</CodeGroup>

The default list view is **`mine`**: your personal tasks, plus team tasks suggested to you or claimed by you. Pass a team to see everything in it.

Filters: `status` (comma list of `open,claimed,done,dismissed`, or `all`; default `open,claimed`), `kind`, `assignee=me`, `since`, `limit` (1–200, default 50), and an opaque `cursor` for paging.

## Processors

A mounted skill declares `tasks: { handles: ["process-call"] }` in its manifest. Reading a task then returns a `processors[]` array — the mounted skills in scope that know how to do this kind of work, each with a ready-to-paste invocation for MCP, the CLI and the Claude Code bootloader.

`agent_load { task }` binds a session to a task you hold (claiming it for you if it's open), extends the lease to cover the session, and renders the task into the brain's system prompt. See [task-bound sessions](/concepts/mounted-agents#task-bound-sessions).

## How operators see it

The dashboard's inbox has a **Tasks** tab with the same filters, and a detail page per task showing its body, payload, results and full timeline. Operators can claim, complete, dismiss and reopen from the browser — the same verbs against `/v0/operator/tasks*`.

## Limits and gotchas

* **A lease expiring is not a failure.** It returns the task to `open` for whoever's next. If your run is long, `touch` it.
* **Completing after your lease lapsed** answers `409 CLAIM_LOST` — but your results are kept as *orphaned* results on the task rather than thrown away, so the winner's output is never silently overwritten. Re-claim and complete again.
* **Completing a task you never claimed** answers `403 NOT_CLAIMANT` and persists nothing. Keep your results client-side, claim, retry.
* **`since=0` and negative values are `400`**, not an empty list. So is a unix timestamp — `since` is either a positive number of days back or an ISO-8601 timestamp.
* **A cursor is opaque.** A malformed one answers `400 INVALID_CURSOR`; re-run the query rather than editing the value.
* **`due_at` is informational.** Nothing sorts or filters on it. Lists are newest-first by creation time.
* **Re-running a processor is your responsibility.** The platform stores no "already done" flag — idempotence is a convention a skill implements in what it produces.

<CardGroup cols={2}>
  <Card title="Sources" icon="satellite-dish" href="/concepts/sources">
    Scheduled producers that file tasks automatically
  </Card>

  <Card title="Activity & wake" icon="wave-pulse" href="/concepts/activity-and-wake">
    The feed every transition writes to, and the boot digest
  </Card>

  <Card title="Mounted agents" icon="robot" href="/concepts/mounted-agents">
    Processors, `tasks.handles`, and task-bound sessions
  </Card>

  <Card title="Dashboard" icon="table-columns" href="/concepts/dashboard">
    The Tasks tab and per-task timelines
  </Card>
</CardGroup>