IPC Connection Recovery
When a client connects to the JAATO server via IPC, the connection may be interrupted by server restarts, crashes, or network issues. The IPC recovery mechanism provides automatic reconnection with exponential backoff, preserving the user's session and conversation state.
IPCRecoveryClient in your client code, see the
Connection Recovery Guide.
Connection State Machine
The recovery system is modeled as a state machine with six states:
| State | Description |
|---|---|
DISCONNECTED | Initial state, or recovery gave up after max attempts |
CONNECTING | Attempting initial connection to the server |
CONNECTED | Active connection, events flowing normally |
RECONNECTING | Connection lost, automatic recovery in progress |
DISCONNECTING | Graceful disconnect initiated by client |
CLOSED | Terminal state, no more connection attempts |
Key Transitions
| From | To | Trigger |
|---|---|---|
DISCONNECTED | CONNECTING | connect() called |
CONNECTING | CONNECTED | Successful handshake |
CONNECTED | RECONNECTING | Connection lost (reset, timeout, etc.) |
RECONNECTING | CONNECTING | Backoff timer fires |
RECONNECTING | CLOSED | Max attempts exceeded |
Exponential Backoff
The recovery mechanism uses exponential backoff with jitter to avoid thundering herd problems when multiple clients reconnect simultaneously:
delay = min(max_delay, base_delay * 2^(attempt - 1))
jitter = delay * jitter_factor * random(-1, 1)
final_delay = max(0.1, delay + jitter)
With default configuration (base_delay=1.0, max_delay=60.0, jitter_factor=0.3):
| Attempt | Base Delay | With Jitter (±30%) |
|---|---|---|
| 1 | 1.0s | 0.7s – 1.3s |
| 2 | 2.0s | 1.4s – 2.6s |
| 3 | 4.0s | 2.8s – 5.2s |
| 4 | 8.0s | 5.6s – 10.4s |
| 5 | 16.0s | 11.2s – 20.8s |
| 6 | 32.0s | 22.4s – 41.6s |
| 7+ | 60.0s (capped) | 42.0s – 78.0s |
Configuration
Recovery behavior is configurable via JSON files and environment variables. Configuration is loaded and merged in precedence order: environment variables > project config (.jaato/client.json) > user config (~/.jaato/client.json) > built-in defaults.
| Option | Default | Description |
|---|---|---|
enabled | true | Enable automatic reconnection |
max_attempts | 10 | Maximum reconnection attempts before giving up |
base_delay | 1.0 | Initial backoff delay in seconds |
max_delay | 60.0 | Maximum backoff delay (caps exponential growth) |
jitter_factor | 0.3 | Random jitter range (0.3 = ±30%) |
connection_timeout | 5.0 | Timeout for each connection attempt |
reattach_session | true | Auto-reattach to previous session after reconnect |
Session Preservation
After successful reconnection, the client sends a session.attach command with the stored session ID. The server loads the session from disk (if evicted from memory), sends a SessionInfoEvent with full state, and the client continues normal operation.
What is preserved
- Session ID for reattachment
- Conversation history (persisted on server disk)
- Tool states (managed by server)
What is lost
- Active IPC connection (replaced by new connection)
- In-flight requests (pending permission responses, etc.)
- Real-time event stream (restarted after reconnect)
Error Classification
The recovery mechanism classifies errors to determine whether to retry:
| Category | Examples | Action |
|---|---|---|
| Transient (will retry) | ConnectionRefusedError, ConnectionResetError, asyncio.TimeoutError |
Retry with backoff |
| Permanent (no retry) | FileNotFoundError (socket deleted), "Permission denied", "Authentication failed" |
Transition to CLOSED |