Fault-Injecting the Free Seat: An Offline Fallback Contract for Local-First Agents

Description and use

Implementing a fallback contract that classifies failure types and allocates budgets between remote and local seats eliminates stack traces and preserves user experience.

Problem

A refactor run against a remote seat failed when Wi‑Fi dropped, leaving the user waiting with no result and a stack trace, because the code had no contract for what to do when a seat is unavailable.

Outcome

Implementing a fallback contract that classifies failures, allocates budgets, and routes to a local seat with provenance labeling prevents stack traces, keeps total latency within limits, and preserves user trust.

Workflow

• 1. Classify the failure type (hard partition, soft timeout, error‑free stall, remote 5xx burst).
• 2. Encode budgets in a frozen dataclass (soft_deadline_s, hard_deadline_s, circuit_window_s, failure_threshold).
• 3. Run the turn: try remote first; on ConnectionError or TimeoutError, switch to local using remaining budget and mark provenance.
• 4. Inject failures in CI using fake transports (HealthySeat, PartitionedSeat, SlowSeat) to test each failure class without network access.

Evidence

The incident report was three lines long: a refactor turn had been running against a remote seat, the office Wi‑Fi dropped for eleven seconds, and the turn returned nothing at all.

Source

A fallback contract answers four: which failures are worth retrying, which should hand the turn to the local seat, how long the user waits in each case, and how the interface tells the user which seat actually answered.

Source

The key insight is that a timeout is not a cancellation. A request abandoned after the deadline may still occupy the remote seat and still consume whatever budget that seat has.

Source