Leases

When a pool staffs a stage, it does not run the work itself. It leases the work to a worker. That lease is one unit of running work — one worker, answering for one subject — and it is what you watch and control while the work is under way.

A subject is what the lease is about. Most often it is a single task. But a lease can also answer for a whole workflow, or a whole space, with no task at all.

What a lease is

Most leases are created when a task enters a stage that an assignment rule routes to a pool: the pool leases the task to a worker running its pinned worker version, and the worker works it. This happens with no one in the loop — you do not dispatch it by hand — as long as the stage is configured for it and nothing is holding the task back (see What moves a task without a person).

An inbound rule can also mint one at a task in response to an event — a webhook or an email. A lease minted this way carries a record of the event that triggered it, so the worker can read what it fired on.

A lease can also be minted with no task: a scheduled rule can mint one on a schedule, at a workflow or a whole space as easily as at a task — again with no person in the loop.

A task-subject lease is pinned, when it is created, to the workflow the task was on, and every lease is pinned to the worker version it runs. Those do not change for the life of the lease: if a task later moves to another workflow, the lease keeps the workflow it started on.

What a lease can reach

For a task subject, a worker sees more than the one task it was leased. A lease also reaches the tasks around it — a parent, its children, its siblings, or a whole workflow — so a worker can read the context of the work it was given.

How far a lease reaches is set by the pool, not the worker: the pool's lease scopes decide it, and every lease that pool creates reaches the same way. A pool left at its default reaches the leased task together with its parent, its children, and its siblings. Widen or narrow that on the pool when you configure it.

A workflow- or space-subject lease has no task, and so no surrounding tasks to reach. It reaches its own subject — the workflow, or the space — and its payload carries a description of that subject in place of the task fields a task lease would hold.

What happens when a lease ends

A lease is active while there is work in flight for it, and then it ends. It ends on its own when the worker finishes — recorded as a success or a failure — and an operator can end one early by cancelling it. Cancelling a lease that is still running asks the worker to stop; a lease that has not started yet is cancelled at once.

However it ends, the ending is final: that lease takes no more work, and its outcome is written to the task's timeline. A pool does not reuse an ended lease — if the work needs another attempt, the pool leases the task again, which is a new lease.

Ending a lease is not the same as advancing the task. A lease finishing records that the work ran; it does not move the task to the next stage. Three things move the task:

• a sentinel rule, and only once every lease of the pools named by the stage's assignment rules that apply to the task, created since the task entered the stage, has ended. A lease of any other pool does not hold a sentinel rule back, for example one started by a scheduled rule, an inbound rule, an assignment to a pool, or a target: parent rule at a child's stage. A sentinel rule can move the task while that worker is still running on it.
• a worker whose lease reaches the task. With tasks_transition it does not wait for the task's other leases to end. With tasks_transfer it is refused while any other lease on the task is still active.
• a person

See What moves a task without a person § A worker moves a task.

An old lease's detail is reclaimed

A finished lease does not keep its full detail forever. After a retention window — whose length the operator running your instance sets — Cadence reclaims the detail of every ended lease past that window, to recover storage. A lease is reclaimed only once it has ended and, if it was working a task, that task has been resolved.

Reclaiming a lease clears the bulky parts of it:

• the prompt the worker ran from (its agent instruction),
• any credential values it resolved,
• the summary the worker reported,
• its final outcome, and
• its attachments.

The lease itself is not deleted, and neither is anything you bill or audit from it. The lease row, its usage and billing records, and its whole activity timeline — including the entry recording how it ended — are left intact. So a reclaimed lease still lists, still reads, and still shows what it did on the task's timeline; only its cleared detail is gone.

This is why the drawer for an old lease shows a notice in place of the cleared fields: Detail reclaimed … ago — this lease's prompt, credentials, summary, outcome and attachments were cleared by the retention sweep. Its billing and activity are unaffected. That is a data-retention behaviour to expect on old leases, not a fault. What it means for reading a lease from a program or a terminal is covered in the Leases reference.

What still needs you

A lease runs and ends without you, but some things around it do not:

• Cancelling a running lease is yours to do. A worker finishes on its own; stopping one before it does is an operator action.

• A pause holds until it is lifted. You can pause a running lease, and a pool that is paused stops taking new leases. Neither resumes on its own — you or the pool lifts the pause.

• A held or blocked task waits for most rules, not all. While a task has a blocking hold, an uncleared dependency, or an unpassed require check at its stage, its stage's assignment rules and inbound dispatch-worker rules start no lease for it. Three things are different, and create their lease anyway:

  • a scheduled rule with the task as its subject
  • an assignment rule with target: parent at a stage one of the task's children enters. Cadence checks the hold, dependency and check conditions against that child, not against the task it leases.
  • an assignment of the task to a pool, made by a person with the task's Assignee field or by anyone with tasks_assign, including a worker whose lease reaches the task. See What moves a task without a person § A person or a worker assigns a task to a pool.

  Each one's worker runs despite a dependency or an unpassed check on the task. While the task has a blocking hold, the worker is refused when it tries to start: over MCP lease_claim answers task is on hold, and over the HTTP API the claim answers 409 task_on_hold. See Scheduled rules § A scheduled rule at a held or blocked task for what that refused lease looks like and what to do. Cadence never clears a blocking hold on its own, and the clear tools refuse a worker. A worker whose lease reaches the task can still replace it with an advisory hold (see Tasks § Holds).

To watch and control a running lease from a program or a terminal — list leases, read one, read a worker's logs, or cancel one — see the Leases reference.