# States

Every state Borago Board shows, as tables. Task columns, owners, queue holds, Docker states, container failures, notification kinds and cloud sync.

A task sits in one of 6 columns, is owned by the board or by a person, and can carry two markers that say it is waiting on you. Around it, the queue can hold for one of 10 reasons, Docker is in one of 4 states, or unknown while a probe has not finished, a container start can fail in one of 7 recognised ways, one of which the table below shows in its two forms, and the bell shows 20 kinds of notification. This page lists every one of those states with what puts a thing in it, what takes it out, and what you see. The sentences the app shows for each are collected on the [Messages](/docs/reference/messages/) page.

The desktop app runs the queue and raises the notifications. A browser on the local network sees the same board. The cloud browser and the phone see the desktop's holds and Docker state relayed from the connected desktop, and see nothing about them while the desktop is off.

## Task status

The board has six columns.

| Column | What it means | How a task gets in | How it gets out | What the user sees |
|---|---|---|---|---|
| Planning | The task is being written. Nothing runs it. | Every task is created here. The agent's own breakdown of a task also creates its new tasks here. Stopping a run moves the task back here. | A drag to another column. Tasks the agent split off and marked to run are promoted to To Do by the board once their prerequisites are recorded. | The column with the Add task button. The card is editable in place. |
| To Do | Queued. The auto-queue takes board tasks from here, one per project at a time, in the order the cards are arranged. | A drag from any column. A run that failed and will retry puts the task back here. A run whose sign-in was rejected puts it back here. A run cut off by a rate limit puts it back here. Answering the last open question on a task returns it here. An app restart returns any run that was interrupted here. | The queue claims the first eligible card and moves it to In Progress. A drag moves it anywhere. | A plain card. When the queue cannot start anything, a hold banner at the top of this column says why, sometimes with a Resume button. |
| In Progress | A run is executing, or a run paused mid-task to ask a question while someone had the task open, or the run parked itself on a declared wait. | Only the queue or the Run button moves a board task here. A user task can be dragged here. | The run ends in Done or Blocked, or falls back to To Do on a retryable failure. Stop moves it to Planning. | A spinner and an amber title while the agent works, with a run timer. After 5 minutes with no output the marker turns red and reads Task may be stuck. A paused question flashes in the open task. |
| Done | The run reported the task finished, or a person marked it done. | The run's final status, or a drag. A finished run lands at the top of the column. | A drag. Dragging a done board task to To Do asks for confirmation, because it runs again. | A card, sometimes with the Needs your attention marker when the run left manual steps or did not declare an outcome. |
| Blocked | The task cannot proceed without a person. | The run said so, the run asked a question with nobody watching, retries were exhausted, the check before a retry judged another run pointless, the provider account had no credits or no access to the chosen model, the run stalled, the request failed with an error a retry cannot fix, the provider was unreachable on six consecutive attempts, or a drag. | Answer the question, or drag it to To Do or Planning. | A card with a red column heading. The reason is a comment on the task. Blocked work also gates the queue, see the hold reasons below. |
| Canceled | Set aside by a person. | A drag. The app never cancels a task itself. | A drag. | A grey card. |

Separately from its column, any task can be closed by dropping it on the Closed zone that appears while dragging. A closed task keeps its column and is hidden unless the Closed filter is on.

### Transitions the queue makes

The queue runs only board tasks in To Do. It takes the cards in their arranged order, skips a card that names an unfinished prerequisite with a task mention, skips a card whose text overlaps a Blocked task's, waits for a card whose pre-run review is still running, and claims the first survivor. Claiming moves the card to In Progress and starts its timer. Only one task runs per project at a time, because tasks share the project's container.

### Transitions a drag makes

A drag can put a task in Planning, To Do, Done, Blocked or Canceled. A board task cannot be dragged into In Progress, because a task enters that column only when a run starts. A user task can be, since a person is its worker. Dragging a running card first asks whether to stop the run. A drag of a done board task to To Do asks whether to run it again. A drag to To Do or Planning clears the needs-attention marker, the container-error marker and the retry count.

### Transitions a run makes

A run ends by writing Done or Blocked. A failed run goes back to To Do and retries after growing delays of 1, 3, 5, 10 and 30 seconds. After 6 failed attempts the task is Blocked. From the second failure on, a cheap model reads the failure first and can stop the retries early, which also blocks the task. A run that asks a question pauses in In Progress if the task is open on the desktop or a local browser, and in Blocked otherwise. A run whose provider rejected the credential, or hit a rate limit, or hit a provider outage goes back to To Do.

### The question guard

A board task with an unanswered question cannot be moved to To Do or In Progress, by drag or by any client. To Do is what the queue picks up, so the move would start a fresh run that asks the same question again and the answer being typed would be lost. The refusal reads: This task is waiting on you - answer its question or clear the action first. You can still close it or move it to Blocked. The card also refuses its own drag, and a drag attempt opens the task instead. Done, Blocked and Canceled stay reachable, so closing a task never requires answering it first. User tasks are exempt, since nothing runs them.

## Task owner

| Owner | What it means | How a task gets it | How it changes | What the user sees |
|---|---|---|---|---|
| Board | The agent runs it. The default. | The Owner select on the task form. | Edit the task and change the Owner select. | The queue, the Run button, the pre-run review and the confirmation before re-running a done task all apply. |
| User | A card for a person. The agent never runs it. | The Owner select on the task form. | Edit the task and change the Owner select. | No Run button applies. It can be dragged into In Progress. Dragging it from Done to To Do needs no confirmation. The question guard does not apply. |

## Two markers that say the task is waiting on you

Both are computed, not stored, so every device shows the same answer.

| Marker | What it means | How a task gets it | How it goes away | What the user sees |
|---|---|---|---|---|
| Awaiting response | A question on the task has no answer yet. The question came from a run or from the pre-run review. | The run ended with a question, or the review posted one. | Answering every open question. A review question also expires when the task text is rewritten, since the words it asked about are gone. | A violet marker reading Waiting for your answer. The task cannot be moved to To Do or In Progress. |
| Needs manual action | The run finished but left something for a person, or a review flagged the result. | A run with manual steps, a run that ended without declaring an outcome, a pull request link to open, a post-run review verdict, or a pre-run review suggesting a rewording or a duplicate. | Moving the task to To Do or Planning clears it, and so does the control in the task. | A teal marker reading Needs your attention. The task can still be moved anywhere. |

They differ on purpose. Moving a task to To Do is the acknowledgement of a note, so a note must not block the move. A question has a paused run behind it, so the move must wait for the answer.

## Docker state

The desktop probes Docker every few seconds. The banner at the top of the board reacts to the state. Nothing renders until the board has tried and failed, and a state has to hold for a few seconds before any strip appears.

| State | What it means | How it gets in | How it gets out | What the user sees |
|---|---|---|---|---|
| Running | The Docker command was found and the daemon answered. | Docker starts. | Docker stops, or the daemon refuses the user. | No banner. |
| Down | The command was found and the daemon is silent. | Docker Desktop was quit, or the Linux service is stopped. | Docker starts. | With Start Docker automatically on (the default), the board launches Docker itself. Nothing shows for the first seconds, then an amber strip while it starts. If the launch fails or times out, a red strip with a Start Docker button. On Linux, when starting needs a password, a neutral strip with the Start Docker button, since only a press may raise a password prompt. On a Mac whose copy of Docker Desktop is still being installed, a neutral strip that re-checks by itself. |
| Permission | The daemon runs, but this user cannot open its socket. Linux only, the docker group. | The user is not in the docker group, or was added to it after the app started. | The group takes effect for the app, by the Fix access step and a restart of the app, or by a new login. | A neutral strip with a Fix access button. After the fix, a strip saying the user was added to the docker group and the app has to restart, with a Finish button. If the fix failed, a red strip with an Open the fix button. Starting Docker is never offered here, because it would fix nothing. |
| Missing | No Docker command anywhere on this machine. | Docker is not installed, or was removed. | Docker is installed. | On a fresh desktop the setup guide opens itself, once. Afterwards a neutral strip with a Set up Docker button. After a guided install that failed, a red strip with an Open Docker setup button. |
| Unknown | The probe did not finish, or the state is being relayed from a desktop that has not reported it. | A lagging machine, or an older desktop on the other end of the relay. | The next probe answers. | The last known state stays, marked stale. Buttons are disabled, not hidden. A browser or phone with no connected desktop shows nothing about Docker. |

While a setup job runs, whichever state applies, an amber strip says Docker or gVisor is installing and asks you to keep the app open. On the cloud browser and the phone, a red strip says Docker is not installed or not reachable on your desktop, and offers nothing, because Docker cannot be started over the relay.

## Container start failure kinds

When a container fails to start, restart or rebuild, the app reads the whole Docker transcript and names the one cause it recognises, in this order of preference. The most actionable cause wins, not the one Docker mentions first. The result is a container error notification, routed to the project settings tab that holds the fix.

| Kind | What it means | The sentence | Tab the notification opens |
|---|---|---|---|
| Port conflict | Another project or program already listens on a published host port. | Host port (the port) is already in use, so the container could not start. Another project or another program on this machine is already listening on it. Change this project's published port, or stop whatever is holding it. | Ports |
| Daemon down | Docker was not reachable when the start ran. | Docker is not reachable, so the container could not start. Use the Start Docker button on the board, or start the docker service (on Linux) or Docker Desktop (elsewhere), then try again. | Containers |
| Name conflict | A container with this project's container name already exists. | A container named (the name) already exists, so this project's container could not start. Remove or rename the existing one, or give this project a different container name. | Containers |
| Mount missing, Docker Desktop form | Docker Desktop refused to mount the project's local path, usually because the path came from another device. | Docker Desktop refused to mount (the path), followed by the explanation and the pointer to the Local path field or Docker Desktop's file sharing settings. | Project Info, with the Local path field focused |
| Mount missing, Linux form | A folder the compose file binds does not exist. | The folder this project mounts does not exist, with the path when Docker named it. Check the project's local path, then start it again. | Docker Compose |
| Arch mismatch | A base image is not published for the chosen CPU architecture, the image on disk was built for another one, the Dockerfile adds Ubuntu's i386 packages on an arm64 machine, or a binary is for another architecture. | One of four sentences, each ending with where the architecture control is. See the Messages page. | Containers |
| Image build | The Dockerfile failed to build, for a reason other than architecture. | The project image failed to build, followed by the last error line Docker printed. | Dockerfiles |
| Unknown | Nothing above matched. | Docker's own last error line. If Docker said nothing, The container failed to start, and Docker gave no reason. | Containers |

Two related failures are not kinds of this list but arrive the same way. If the container started and the repository could not be cloned into it, the notification says the container was started but the repository was not cloned, and opens Project Info. If a project's local path does not exist on this machine, the start is refused before Docker runs and the notification opens Project Info with the Local path field focused. If the project is pinned to an architecture this machine cannot run, the start is refused before the build and the notification opens Containers.

## Queue hold reasons

A hold is why the auto-queue is not starting anything in a project. It shows as a banner at the top of the To Do column with a short label, the sentence built where the hold was decided, and sometimes a time, which is when the queue resumes on its own. Resume is offered only where pressing it can do something. Manual runs with the Run button are never held.

| Reason | What decides it | Label and sentence | Time shown | Resume |
|---|---|---|---|---|
| Blocked interference | Every To Do task's text overlaps a Blocked task's, so starting any of them would step on half-done work in the shared container. | Auto-run paused - blocked work, then the name of the blocked task and Answer, retry or close it to continue. | None | No. It would re-apply at once. Unblock the named task instead. |
| Prerequisite | Every To Do task names an unfinished task as a prerequisite with a task mention. | Auto-run paused - waiting on a prerequisite, then the task it waits on. | None | No. Finishing the prerequisite re-triggers the queue. |
| Rate limit | The provider answered with a rate limit. | Auto-run paused - provider rate limit, then The provider returned a rate limit. Tasks already running are not affected. | Resumes at a time. A deadline. The provider's stated reset plus a margin, or a growing backoff when it stated none. | Yes. Resume runs anyway. |
| Auth | The provider rejected the stored credential, on a run or on the free check before a run. | Auto-run paused - sign-in needed, then the sentence asking you to sign in again. | None | Yes, and a successful re-entry of the credential in the project's AI Auth tab lifts the hold by itself. |
| Cost budget | This machine's estimated spend for the provider reached the budget set on the project. Per provider. | Auto-run paused - cost budget, then the provider, the budget, the spend so far and Reset the spend to resume. | None | No. Reset spend in the provider's card on the AI Auth tab lifts it. |
| Retry exhausted | A task failed every retry, which pauses the whole project queue. | Auto-run paused - a task failed every retry, then the task's name and Resume to try again. | None | Yes |
| Credits | The provider account has no credits or quota left. | Auto-run paused - API credits exhausted, then Top up the provider account, then resume. | None | Yes |
| Task failed | A task failed on its first attempt with an error a retry cannot fix, or the provider was unreachable on six consecutive attempts. | Auto-run paused - a task hit an error a retry cannot fix, then the task's name, the error, and Fix it on the task, then resume. | None | Yes |
| Model access | The provider refused the chosen model with a message saying it requires usage credits. | Auto-run paused - no access to the chosen model, then the model's name and Pick a model your plan includes, or enable usage credits, then resume. | None | Yes |
| Firewall blocked | Container management is on and this machine's firewall drops the container's connection to the policy proxy. Checked before the run is claimed. | Auto-run paused - allow Docker access through the firewall, then the port and the firewall rule to apply. | None | Yes. Resume checks the connection again. |

After the app restarts, a rate limit wait survives but its reason does not. The banner then reads Auto-run paused, waiting until the time before starting anything new, and offers Resume.

On the cloud browser and the phone the hold arrives relayed from the desktop with its reason as the desktop recorded it.

## Notification kinds

The bell in the top bar lists notifications newest first. Each kind has a colour dot. Some kinds coalesce, which means a repeat of an unread notice for the same project updates that notice in place and records the repeat in its history instead of adding a row. A repeat of a notice already read inserts a new one. All kinds are raised by the desktop unless the table says otherwise. The list is capped at 300.

| Kind | Colour | What it means | Coalesces | A click opens |
|---|---|---|---|---|
| Auth failed | Red | The provider rejected the stored credential, on a run or on the check before a run. The project queue is held. | Yes | The project's AI Auth tab |
| Task blocked | Red | A run ended in Blocked because the agent said so, retries ran out, the check before a retry stopped early, the provider had no credits or no access to the model, the run stalled, the request failed with an error a retry cannot fix, or the provider was unreachable six times. | No | The task |
| Task question | Amber | A run asked a question while nobody had the task open, or the task was closed with the question unanswered, or the pre-run review has questions. | No | The task |
| Task action required | Blue, with an Action needed badge | A run finished with manual steps, or ended without declaring an outcome, or left a pull request to open. The post-run review flagged the result. The pre-run review suggests a clearer wording or a possible duplicate. Work was split into new tasks. A synced project needs a folder on this device. | No | The task, or the project when the notice has no task |
| Container error | Red | The container was not running when a run started. A start, restart or rebuild failed. The repository could not be cloned. The container crashed, ran out of memory or keeps restarting. A script failed. A self-hosted server's context window is too small or unverified. An automatic Dockerfile change did not build. The Docker client could not be installed. A provider was unreachable while its status page was green, which points at the container's own network. | No | The tab the notice names. Otherwise the task. A project-level notice with no task opens the restart container confirmation. |
| Firewall blocked | Red | The host firewall blocks the container's access to the policy proxy. | Yes | The project's Containers tab |
| Git auth error | Red | The stored git key cannot be decrypted on this device, or the project links to a saved key that is not in this device's vault. Runs and terminals get no git credential. | Yes | The project's Project Info tab |
| Rate limited | Amber | The provider rate-limited a run and the project queue is paused. The time it resumes is shown in your own clock format. | Yes | The project settings |
| Queue held | Amber | Every To Do task overlaps blocked work, or the cost budget is reached. | Yes | The project settings |
| Task error | Red | The run finished but its results could not be saved. A declared wait timed out. The provider is reporting a service problem and the task will retry. Tasks the run proposed could not be created. | No | The task |
| Update available | Blue | A newer desktop version exists. Still downloading, or an install the user updates themselves. | Replaced by an update ready notice | The download page, or Settings, Application |
| Update ready | Green, with an Action needed badge | The update has downloaded. | Replaces an unread update available notice | Restarts the app to install it |
| Container notice | Blue | A fact about how the container runs on this machine, nothing broken. It runs under CPU emulation, or its Dockerfile looks like it needs the other architecture. | Yes | The project's Containers tab |
| Secret removed | Amber | A credential was removed from the project by a change synced from another device. The previous value is held on this machine for a while. | No | The project tab that holds the credential |
| Container rebuild needed | Blue, with an Action needed badge | A task installed or removed tools and the Dockerfile changed, or container settings changed on another device. The running container is behind the file until it is restarted. | Yes | The start or restart container prompt |
| Flow failed | Red | A flow run ended in an error, or could not run. | No | The flow's page |
| Security alert | Red | Reserved for the cloud service. | No | Nothing |
| Account notice | Blue | Raised by the cloud for an announcement, and by the desktop's sync engine when the cloud session is no longer valid or another desktop took the account's link. | No | Settings, Account |
| Credential storage weak | Amber | The key that seals every stored credential on this device is itself not sealed by a real keychain. Raised once per launch while that holds. | Yes, one notice for the account | Settings, Account |
| Container ready | Green | The Docker client that container management installs in the background has landed in the running container. | No | The project's Containers tab |

While unread, a notice offers a check mark to read it in place. Every notice offers a cross to remove it and a copy button. A notice with a project also offers Create task and, where chat is available, Ask in chat. Reading a notice on one device clears it on every device of the account.

## Credential storage

The desktop seals the key that encrypts every stored credential with the operating system's credential store. It checks that seal and reports the weakest state seen this session. The warning appears in Settings, Account, beside the cloud sign-in, and once per launch in the bell. Nothing is ever blocked.

| State | What it means | What the user sees |
|---|---|---|
| Protected | The key is sealed by macOS Keychain, Windows DPAPI or a Linux Secret Service such as gnome-keyring or KWallet. | Nothing |
| Locked | The key is sealed, and the keyring cannot open it this session, for example on Linux before the keyring unlocks. Nothing is exposed. | No warning. Saving or reading a stored credential says the keyring is locked and asks you to unlock it. Stored credentials are unreadable until the next launch. |
| Weak protection | The key has only weak protection, because the Linux desktop had no keyring when an older build wrote it. | Your stored credentials have only weak protection, and a sentence naming the missing keyring. |
| Unprotected | No protection was available, so the key is on disk in the clear. On Linux this is the desktop with no keyring. | Your stored credentials are not protected, with the missing keyring named when that is the cause. |
| Denied | macOS asked whether the app may use the keychain and the answer was Deny. | Your stored credentials are not protected, and a sentence saying the app was denied access to the keychain. |

An unknown Linux keyring is not called weak. The warning is raised on positive evidence only.

## Cloud sync and the device link

Cloud sync is off by default and desktop only. Once signed in, the profile icon in the top bar carries a dot, and Settings, Account shows a status line.

| State | How it gets in | How it gets out | What the user sees |
|---|---|---|---|
| Off | The default. | Turn on Cloud sync in Settings, Account, and sign in. | No dot. |
| Waiting for sign-in | Cloud sync is on and no account is signed in on this device. | Sign in. | The status line reads Not connected yet - save to start syncing, or an error saying to log in to cloud sync. |
| Connected | The last request the cloud answered succeeded. | Any failure below. | A green dot labelled Cloud connected. The status line reads Connected with the time of the last sync and counts of records sent and received. |
| Syncing images | Connected and transferring attachment bytes in the background. | The transfer ends. | An animated blue dot labelled Syncing images in the background. |
| Not connected | A request failed and nothing has succeeded since. Offline, or the cloud is unreachable. Every failure below also shows this dot. | The next request succeeds. | A red dot labelled Cloud not connected. The status line shows the error. |
| Session expired | The session, 30 days long, ran out while the desktop was off, or the password changed. | Sign in again under Settings, Account. | A red dot, the status line saying the session has expired, and a bell notice titled Cloud sync signed out. |
| Subscription required | The account has no active plan. | Subscribe from the profile page. | The status line reads An active subscription is required to enable sync, with a View profile link. |
| Update required | This desktop is older than the cloud's minimum supported version. Sync stops so an old record format never reaches the cloud. | Update the app. | An amber dot and a banner reading Update required to keep cloud sync working, naming the version to update to. The local board keeps working. |
| Another desktop linked | A different desktop signed in to the same account and took its single desktop link. | Sign in again from Settings, which links this desktop back and sends what it changed meanwhile. | A banner reading Another computer is now linked to your account, a red dot, and a bell notice titled `Cloud sync stopped: another desktop is now linked`. The local board keeps working. |
| Account deactivated | The account was deactivated from the cloud profile. | Reactivate it there. | The status line says the account is deactivated. |

One desktop per account. At sign-in the desktop sends a random installation id. If another desktop already holds the link, a confirmation titled Link this desktop app? asks before the link moves, since the other desktop then stops syncing and loses its remote terminals until it links back. Browser and phone sign-ins never touch the link.

Related: [Messages](/docs/reference/messages/), [The queue and its holds](/docs/reference/queue-and-holds/), [Notifications reference](/docs/reference/notifications/), [When the agent asks a question or needs you](/docs/guides/questions-and-actions/), [The troubleshooting map](/docs/for-ai/troubleshooting-map/).