Agent Sessions
An agent session is one queued unit of work. A claim is the active lease that lets one eligible worker execute that session.
Keeping sessions and claims separate prevents duplicate runs and makes agent progress visible before the underlying initiative, bug, or todo changes state.
Queued work is not running
Creating a session only puts work in the queue. A worker can start only after it claims the queued initiative, bug, or todo.
Monitor sessions in the dashboard
Open Work queue from the main menu or the desktop title bar to see queued, running, and recently finished sessions without leaving the current page. The badge shows how many sessions are queued or active. Select a row to open the run, or choose View all to open Agents.
The list shows up to ten sessions. Recently finished sessions stay visible for about eight hours before they drop off the list. That cleanup is automatic; archive is a manual action that hides a finished session immediately.
Archive finished sessions
Archive hides a finished session from session lists in Worker queue, agent run tables, and the Agents area. The underlying initiative, bug, or todo and its activity history stay in place.
Archive is available when a session is complete, error, or cancelled. Pending, queued, running, or otherwise active sessions must finish or be cancelled before you can archive them. Stale sessions show Try again in the dashboard; retry the run, then archive the finished retry.
Open the run actions menu on a finished session and choose Archive. Confirm when prompted. Archived sessions leave the list immediately and cannot be restored from the dashboard.
Session list APIs exclude archived sessions. Workers cannot claim an archived session.
For Codex local runs that include a thread ID, Open in Codex appears in Work queue, on run details, or in the run menu. See Codex for deep links and troubleshooting.
What a session stores
| Area | What it stores |
|---|---|
| Scope | Workspace, agent, execution mode, and initiating user. |
| Local ownership | The signed-in owner when the session must run on that owner's machine. |
| Target work | The initiative, bug, or todo the agent was asked to handle. |
| Instructions and context | The prompt, trusted instructions, and untrusted work context. |
| Run state | Active claim ID, plan text, external URL, Codex thread ID when the worker reports one, pending resume input when someone replies to an input request, error message, and timestamps. |
Desktop, CLI workers, and custom workers use the same lifecycle. Starting a local worker from Desktop does not bypass claims; it starts a process that can heartbeat, poll, and claim sessions for the signed-in owner.
Session states
| State | Meaning |
|---|---|
queued | Waiting for an eligible worker to claim it. |
pending | Accepted by the platform but not ready to execute yet. |
active | A worker holds an active claim and is executing. |
awaiting_input | The worker paused and needs a user reply before it can continue. |
complete | Work finished successfully. |
error | Work failed or could not be completed. |
stale | A worker stopped heartbeating or the claim expired. |
cancelled | The user or system cancelled the session. |
Claim rules
A claim is scoped to one workspace, agent, worker, and session. It proves that a worker can run that session right now.
When a worker claims a session, the platform checks the basic boundaries before the worker can run.
Same workspace and agent
The worker must belong to the same workspace and agent as the session.
Matching execution mode
A local worker can claim local sessions. A cloud worker can claim cloud sessions.
Local owner
For local sessions, the signed-in user must own the worker.
Target worker
If the session specifies a target worker, only that worker may claim it. Sessions created through the Send to launcher for a specific worker destination are automatically targeted. Untargeted sessions are claimable by any eligible worker for that agent.
No active claim
Only one active claim can exist for a session. Stale claims can expire or be released before a new claim starts.
Stale session ownership
When a session is stale, only the worker that made the most recent claim can claim it again. Poll requests that include stale sessions return only sessions last claimed by that worker. Use Try again in the dashboard to queue a new session when you want a different worker or a fresh run.
Pass leaseSeconds in the claim request to control how long the lease is valid. The default is 900 seconds. If the lease expires before the worker completes or fails, the platform can mark the session stale. Only the worker that made the most recent claim can reclaim that stale session.
Every session update must include the active claimId. Activities, metadata updates, completion, failure, and release calls without the active claim ID are rejected.
Resume when a session awaits input
When a worker marks a session awaiting_input, the run pauses until someone sends a reply. In the dashboard, choose Resume on the session in Work queue, on the run detail page, or in the Agents area. Enter your reply in the Resume session dialog and confirm.
The reply can be up to 20,000 characters. The platform stores it as pending resume input, keeps the active claim, and refreshes the claim lease. The owning worker must be online; if it is offline, resume fails until that worker heartbeats again. Only one pending reply can be queued at a time.
The owning worker consumes pending resume input on its next poll and continues the run. Custom workers should treat an awaiting_input session with pending resume input as a resume activation rather than a new claim. OAuth clients can queue the same input with POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/sessions/{sessionId}/resume.
By default, an awaiting-input pause does not change the linked initiative, bug, or todo status and does not post a task comment. Agent blueprints can configure a different status or comment behavior when they need it.
Activities
Workers emit activities for progress that belongs in the dashboard or audit history:
progressplan_updatedexternal_url_updatedawaiting_inputuser_resume_inputcompletedfailedpolicy_decision
Activities are visible progress events. Heartbeats only show that the worker is alive and should not be used as progress updates.
Use session metadata for plan text, external URLs, input requests, and error messages.
Complete, fail, or release
Complete a session when the work succeeds. Fail it when the worker cannot finish and the session should be marked as errored. Release it when the worker stops before doing useful work or decides another eligible worker should retry. Release puts the session back to queued for any eligible worker; it does not mark the session stale.
If a worker misses heartbeats for 12 seconds, the platform marks it stale. After 5 minutes without a heartbeat, the worker is marked offline and its active claims are expired. Affected sessions become stale, and the worker that last claimed each session can reclaim it when it polls again. Use Try again in the dashboard to queue a new session on a different worker.
Work state updates
Agent blueprints can apply state transitions from session lifecycle events. Workers do not need to write those state changes directly.
| Session event | Default state |
|---|---|
| Session claimed | In Progress |
| Session completed | In Review |
| Session awaiting input | No change by default. Blueprints can set Blocked or another status. |
| Retries exhausted | Blocked |
Worker runtime configuration can narrow allowed updates, but it cannot expand beyond the blueprint permissions.
Human review
Treat completed sessions as delivery evidence, not automatic approval. Check the resulting code, tests, pull request, comments, or linked external URL before marking the underlying work done.
For built-in local execution, read Local Workers. For custom integrations, choose Build a Local Agent or Build a Cloud Agent.