States

Polo uses a small set of state words, and each one has a precise meaning. This page lists them by where you see them. Words in code font are the values stored by the API; the words beside them are the labels the app shows.

The words are taken from the code: api/src/modules/*/domain/ for the stored values and ui/shared/ and ui/features/ for the labels.

Capability maturity levels

Shown on Settings → What Polo can do, one per capability area. Defined in full on Capabilities.

Label	Meaning
Planned	No code in this build.
Implemented	Code exists, but only unit or component tests cover it, or its end-to-end test cannot run.
Verified locally	A test or recorded run drives the real path end to end against local fixtures or real local tools.
Verified with a provider	A recorded run against a real external account. Nothing has reached this level.
Operated in a pilot	Used for real work in a pilot. Nothing has reached this level.

Connection states

On a capability area

Each area on the Capabilities page shows the state of the connection it needs in your workspace.

Label	Meaning
Connected	Polo reached this connection, or checked it when it was set up, and its latest request did not fail.
Registered	Saved by an administrator and not reached yet. Polo first reaches a runner or endpoint when a task uses it, and hears from an alert source only when it delivers a signed alert.
Set up	Set up inside Polo. Used for things that need no outside system, such as team knowledge, the service catalog, a recurring task or an uptime monitor.
Error	The latest request through this connection failed. The reason is shown with it. The README and the in-app help also call this Reach failed.
Paused	The thing the area depends on exists but is switched off, such as a paused monitor. It no longer counts as connected.
Needs a connection	Nothing is registered for this area yet.
No connection needed	The area needs only a model route.
Planned	The area is planned, so there is nothing to connect.
Checking…	The page is still loading the state.

The difference between Connected and Registered matters. Registering a runner contacts nothing. A connection is Connected only after a real request got a usable answer.

On the Connections page

Label	Meaning
Connected	A request through it reached its runner or provider, and none has failed since. Shown with when, for example “Connected · reached 5 minutes ago”.
Registered	Never reached yet: “Registered · not yet reached”.
Error	The latest request failed: “Error · latest request failed 2 minutes ago”, with a reason from the list below.
Disabled	An administrator disabled it. Tasks can no longer use it.
Needs authorization	An MCP server that signs in with OAuth is waiting for an administrator to authorize it.
Reconnect needed	The provider revoked or expired Polo’s authorization of an MCP server.
Reconnect required	A Google or Outlook account whose grant the provider revoked or expired. Reconnect the account to use it again.

Why a request failed

When a connection shows Error, Polo records one bounded reason code, never the provider’s raw error text (REACH_ERRORS in api/src/modules/operations/domain/reach.ts).

Code	Shown as
unreachable	Polo could not connect to it
timeout	It did not answer in time
tls_failed	Its HTTPS certificate or handshake failed
endpoint_blocked	Its address is outside the approved endpoints
credential_rejected	It refused Polo’s credential or the registered scope
rate_limited	It asked Polo to slow down
runner_error	It answered with a server error
request_refused	It refused the request
invalid_response	Its answer did not match the registered scope
evidence_unavailable	It could not read the system behind it
provider_error	The request failed, and Polo cannot say more precisely where

Runners

On the Runners section, a runner that connects out to Polo shows one of these.

Label	Meaning
Connected	A runner you installed is online.
Not connected	A runner you installed is offline.
Running	A runner Polo manages for the workspace is online.
Stopped	A runner Polo manages is offline.
Failing	The runner is reporting a problem.

Monitors and schedules

Label	Meaning
Healthy	The monitor’s recent probes succeeded.
Failing	The monitor’s probes are failing.
Paused	The monitor or the recurring task is switched off.
No recent checks	The monitor has no recent probe results.
Scheduled	A recurring task is switched on.

Task states

A task and each agent run inside it have one stored status (WorkStatus).

Stored	Label	Meaning
queued	Queued	Accepted, not started yet.
running	Running	An agent is working on it, or it is waiting on a person.
succeeded	Done	Finished, and the supervisor accepted the evidence.
failed	Failed	Stopped without meeting its objective. The reason is shown in plain words.
canceled	Canceled	A person canceled it.

A running task that waits on a person shows who it waits on instead of Running.

Label	Meaning
Waiting for you	There is a question you can answer or a change you may decide.
Waiting for an answer	There is a question that only an operator or administrator can answer.
Waiting for approval	A change waits for a decision that someone else must make.

A question an agent asks is pending until someone answers it, then answered.

Why a task failed

Failure reasons are fixed sentences (runtime/stop_reasons.py). The common ones:

Sentence	Cause
Ran out of time before finishing.	The run passed its deadline.
Ran out of time while waiting for someone to decide on a proposed change.	No decision arrived before the deadline.
Ran out of time while waiting for an answer to a question.	No answer arrived before the deadline.
Reached its step limit before finishing.	The agent used all its allowed steps.
Reached its AI usage limit before finishing.	The token limit was reached.
The remaining budget cannot cover another AI model call.	The money budget was reached.
One or more helpers could not finish their part of the task.	A specialist failed.
Could not verify the result within the allowed follow-up attempts.	The supervisor’s review did not accept the evidence after its rework rounds.

Approval states

A change that waits for approval is an operation request. Its stored status (OperationStatus) is one of eight values.

Stored	Meaning
awaiting_approval	Proposed and reviewed. Nothing has been executed.
running	Approved and sent to the runner. Polo has not confirmed the result yet.
succeeded	Executed, and a separate read confirmed the result.
failed	It was refused before anything changed, or it ran and failed.
unknown	Polo could not confirm whether it ran. See below.
rejected	A person rejected it. Final.
expired	Nobody approved it within its approval window. Nothing was executed.
canceled	Its task was canceled, or the agent that asked stopped, while it waited.

On the Approvals page

Section	Holds
Waiting for you	Changes you may approve or reject now.
Waiting for another approver	Changes you may not decide, for example your own request where self-approval is not allowed.
Questions	Questions agents have asked.
History	Decided and closed changes, outcome first.

A waiting change can also be in one of these positions:

Label	Meaning
Can’t be approved	The agent no longer holds the permission the change needs, or the task’s requester lost their role. It can still be rejected.
Closed	No decision can take effect any more, because the task or the agent that asked has stopped. Nothing will run.

What the History says

Text	Meaning
Waiting for approval	Not decided yet.
Approved · Polo is applying it	Status running.
Applied · Polo hasn’t verified it yet	Executed; the verifying read has not confirmed it.
Applied and verified	Status succeeded with a verified read-back.
Approved, but it never ran	The runner refused it before changing anything.
Approved, but it failed	It ran and failed.
Approved, but it failed and was rolled back	A CloudFormation change that rolled back.
Outcome unknown · Polo couldn’t confirm that it ran	Status unknown.
Rejected by name	A person rejected it, with their reason if they gave one.
Expired: nobody decided in N h	The approval window closed.
Closed: …	The task ended, was canceled or ran out of time before anyone decided.

“under a standing approval” is added when a pre-authorized action approved the change instead of a person.

Standing approvals

A pre-authorized action (Settings → Approval rules) has its own state.

Label	Meaning
Active	It would approve a matching request now.
Daily limit reached	It approved its maximum number of requests today. Matching requests wait for a person.
Expired	Its end date passed.
Not applying	Something it depends on changed, such as a disabled connection, so it approves nothing.

Operation outcomes

The status says where a request is in its life. The outcome says what it came to. The task view counts a task’s changes by outcome (CHANGE_OUTCOMES in api/src/modules/work/domain/change-outcomes.ts).

Outcome	Meaning
verified	A read-back matched what was approved.
created	For a GitHub workflow run: GitHub created the run and it has not finished.
concluded	For a GitHub workflow run: it ended without success or failure (neutral, skipped).
unverified	Executed or executing, with no confirmed result yet. Includes unknown.
failed	It ran and failed.
not_executed	It was refused before execution, canceled, or closed before anyone decided.
rejected	A person rejected it, or it expired.
awaiting	It waits for a person, and a decision can still take effect.

In the task view, each change also answers “did it happen?” in one line:

Line	Status
Pending approval	awaiting_approval
Pending · executing	running
Pending · executed, not yet verified	executed, not verified
Pending · outcome unconfirmed	unknown
Verified	verified
No · rejected	rejected
No · expired	expired
No · canceled	canceled
No · not executed	failed before execution
No · failed	failed after execution

Verification

The verifying read has its own three results (Verification in api/src/modules/operations/domain/operations.ts).

Value	Meaning
verified	The read confirmed the change.
pending	The change is still in progress on the provider’s side.
not_observed	The read could not see the change.

Unknown

Unknown is a real outcome, not an error message. It means a change was approved and sent, and Polo cannot tell whether it took effect: the connection dropped after the request left, or the runner never confirmed.

When an operation is unknown:

• Polo does not send it again. A change is sent once.
• Polo does not report it as failed. It might have happened.
• Other changes to the same target are refused until this one is resolved.
• Running Verify outcome on the task repeats the verifying read. If the read confirms the change, it becomes succeeded; if the runner’s record shows it was refused, it becomes failed.

Costs follow the same rule. A model call whose result never came back is recorded as unresolved spend, shown apart from known spend, and never counted as zero.

Roles

States often depend on who is looking. Polo has three roles.

Role	Can
admin	Everything, including connections, approval rules, standing approvals and team members.
operator	Create and cancel tasks, answer questions, and approve changes where the approval rule allows operators.
viewer	Read only.

Where to go next

• Capabilities for the maturity levels in full.
• Approvals and guardrails for deciding on a change.
• The operation contract for how these statuses are produced.
• Glossary for the terms used here.