---
title: Chat Connection States
description: How Pinchy tracks the health of the agent connection and what each state means for you.
---

Pinchy tracks the health of the agent connection in real time so you always know what's happening — and what to do if something goes wrong.

## The four states

| State       | Indicator     | What it means                                        |
| ----------- | ------------- | ---------------------------------------------------- |
| Starting    | Yellow        | Pinchy is loading your conversation history.         |
| Ready       | Green         | The agent is available and waiting for your message. |
| Responding  | Green         | The agent is generating a reply. You can still type. |
| Unavailable | Red or Yellow | The agent can't be reached right now.                |

## Unavailable reasons

When the state is Unavailable, the indicator and status message explain why:

- **Disconnected** (red): The connection dropped. Pinchy is trying to reconnect automatically.
- **Configuring** (yellow): You recently changed agent settings. Pinchy is applying the changes and will be ready in a moment.
- **Exhausted** (red): Reconnection attempts failed. You need to reload the page to resume.

## Auto-recovery

When the agent runtime becomes reachable again — whether after a network drop or after a settings change — Pinchy automatically requests the latest conversation history and resumes where it left off. No reload needed.

## Brief disconnects don't lock the UI

Pinchy waits 2 seconds before showing the Disconnected state. During those 2 seconds the interface stays in its previous state (Ready or Responding) so short network hiccups are absorbed silently without disrupting your flow.

## Typing while the agent responds

You can type your next message while the agent is still generating a reply. Only the **Send** button and the **Retry** button are disabled during a response — the text input stays active so you can prepare follow-up questions.

## Model-unavailable errors

When the model itself is the problem — not the connection — Pinchy shows a dedicated **model-unavailable bubble** in the chat thread. This is distinct from the connection-state indicators above: the agent runtime is reachable, but the upstream provider returned a server error (HTTP 5xx) that signals the model is offline or discontinued.

The bubble shows the affected agent name, the model identifier, and a plain-English explanation. A **Switch model →** link takes you straight to the agent's model settings so you can pick a replacement without leaving the chat.

See [Manage LLM Providers — Model-unavailable errors](/guides/llm-providers/#model-unavailable-errors) for step-by-step instructions and the list of removed models.

## Upstream format errors

Some providers occasionally reject a request payload because of a known schema defect that retries usually clear — the canonical example is Gemini 3 dropping its required `thought_signature` field on a tool-call replay turn (upstream `openclaw/openclaw#72879`). When Pinchy recognises one of these patterns, the chat shows a dedicated **transient upstream issue bubble** instead of the generic provider-error wording.

The bubble is deliberately different from the model-unavailable one above:

- It names the affected model and explains the cause is **upstream**, not your configuration.
- It tells you to click **Retry** — the same message usually succeeds on the next try.
- It does **not** offer a "Switch model →" link. The model is fine; switching would push you away from the one you actually chose.

Each occurrence writes a throttled `agent.upstream_format_error` audit entry (one per `(agent, model)` per 5 minutes) so admins can track frequency from the audit page rather than grepping gateway logs.

## Navigating away mid-conversation

When you send a message and move to a different page in Pinchy, the chat keeps running in the background. Come back any time during the same browser session and the in-flight reply is right there — no reload, no lost output. A pulse dot next to the agent name in the sidebar shows when an agent is actively responding; a red dot indicates an error on the last turn. Closing the tab or doing a full page reload ends the session.

---

See also: [Message Delivery & Retry](/guides/retry-messages) for how to recover from failed messages.
