Chat Connection States

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 five 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. | | Image too large | Red | An attachment you tried to send exceeds the size cap. |

When an attachment is rejected, the indicator reads Image too large and a banner asks you to send a smaller file before you can keep chatting.

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 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.

A full page reload does not lose the reply either. Pinchy re-attaches the reloaded chat to the in-flight run through its stable session key, so any output that arrived while the page was reloading still lands in the same bubble and streaming continues. Only a restart of the Pinchy server drops in-flight runs.

An unsent message you've typed is kept too. Each chat holds its own draft, so a message you start in one chat never appears in another — and your typed text is waiting where you left it when you return, even after a full page reload or closing and reopening the tab. Sending the message clears the draft; so does deleting the text yourself.

Clicking an agent in the sidebar reopens the chat you last had open with that agent on this device, rather than starting from the oldest one. The first time you open an agent on a new device, Pinchy takes you to your most recent conversation with it.

Paused: agent errors survive a reload

Some agent errors are only temporary — the model provider is rate-limiting requests, is overloaded, timed out, or is briefly unavailable. When one of these interrupts a run, the chat shows an error bubble that names the actual cause (we don't label everything a "rate limit").

That bubble lives in the conversation, so a reload — or a reconnect during a long tool loop — would normally lose it, leaving you unsure whether anything went wrong. Pinchy keeps it instead. The error re-surfaces as a paused banner above the message composer when you come back, with the same cause-specific explanation. From there you decide: Retry resends your last message, or Dismiss clears the banner once you've moved on.

The banner is scoped to you and the agent you're chatting with, so you only ever see the error that's actually yours. Dismissing it clears it for good — it won't reappear on the next reload.

Long-running responses time out

A single response can't run forever. A server-side watchdog caps each run at about 15 minutes of wall-clock time. If a reply hasn't finished by then, Pinchy aborts it and shows a "timed out after 15m — please retry" error bubble with a Retry button so you can send the same message again.

This cap is independent of the connection-state indicator above: the connection can be perfectly healthy and the agent still hit the limit on a genuinely long task. The timeout is per response, not per conversation — retrying starts a fresh run with the full 15-minute budget.

---

See also: Message Delivery & Retry for how to recover from failed messages.