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

# Tasks & Sessions

> Stuck, paused, pending, displaced, and handed-off tasks.

## A task stays pending or reports `queue_wait_exceeded`

* Run [`phone_device_status`](/api-reference/tools/phone-device-status) and
  confirm the selected phone is online and not device-paused
* A task can remain pending while another in-app agent or chat task is using
  the phone's execution lane
* Increase `queue_wait_timeout_s` when the phone legitimately needs more time
  to become available; the maximum is 300 seconds
* If the task reached `queue_wait_exceeded`, start a new task after the phone
  becomes available

## A task stays paused

* Call [`phone_task_monitor`](/api-reference/tools/phone-task-monitor) and
  confirm the task reports `status: "paused"`
* Call [`phone_task_resume`](/api-reference/tools/phone-task-resume) with the
  same `session_id` and `task_id`
* Continue monitoring the original `task_id`; resume does not create a
  replacement task
* Optionally include a short `instruction` if the agent should change course
  after resuming

## The monitor returns before the task is finished

* `status: "paused"` is actionable; resume the same task and monitor its
  original `task_id`
* `monitor_timed_out: true` is **not** a task failure; call
  `phone_task_monitor` again
* A completed `needs_user_control` result requires user input and a
  continuation task - see below
* Use [`phone_task_status`](/api-reference/tools/phone-task-status) only for a
  point-in-time snapshot, not a polling loop

## The phone asks for user input

* `message_user`, confirmation, login, login-details, and CAPTCHA actions
  complete with `terminal: "needs_user_control"`
* Inspect `error.control_type` and `error.prompt` to determine what the phone
  needs
* Send the user's answer with
  [`phone_task_message`](/api-reference/tools/phone-task-message) using the
  completed task's `session_id` and `task_id`
* Monitor the returned `continuation_task_id`; the completed original task
  will not become running again
* Repeating the same answer is safe, but a different second answer is
  rejected

## My task was cancelled and I didn't cancel it

`terminal: "stopped_by_user"` has three sources: [`phone_task_cancel`](/api-reference/tools/phone-task-cancel), [`phone_session_end`](/api-reference/tools/phone-session-end), and **displacement** - starting a new `phone_run_task` on the same device cancels its existing pending, running, or paused MCP task. Serialize work per device, or use separate devices for parallel workflows.

## `session_not_found_or_inactive`

* Start a new session with
  [`phone_session_start`](/api-reference/tools/phone-session-start) (or just
  call `phone_run_task`, which creates one)
* Make sure subsequent task calls use the latest active session
* Avoid reusing a session after calling `phone_session_end`
* Sessions expire - check `expires_at` on long workflows
* If a client caches old tool state, reconnect the MCP server and try again

## `task_not_found`

* Use the exact `task_id` returned by `phone_run_task`; do not construct or
  reuse IDs across sessions
* After answering a `needs_user_control` task, monitor the returned
  `continuation_task_id`, not the original completed task
* Tasks expire; if the correct ID no longer resolves, start a replacement
  task with `phone_run_task`

## A mobile log shows `/mcp-result` returning 404

* This only appears if you are reading the Android app's own device logs; MCP
  clients never see this endpoint
* The 404 is harmless: the phone reported a result for a request that had
  already timed out or been superseded, so the server discarded it
* If your original tool call timed out without a result, retry that tool
  call; there is nothing to fix on the phone

## Other terminal outcomes

Every completed task carries a `terminal`; the [terminal outcomes table](/guides/concepts/task-lifecycle#terminal-outcomes) covers all nine, and [Error handling](/guides/best-practices/error-handling) gives the recovery move for each.