Failure and edge-case behavior

[claude]

Question

What does the app do when things go wrong, and how does it say so?

This graduated from the map's Failure behavior fog, which was waiting on "the architecture taking shape." It has now taken shape: #3 fixed the process split, #5 fixed the seam's error kinds, #7 fixed the surfaces that can display a state, #8 fixed configuration and key storage, #9 fixed the pause/throttle/stop states and their status-pill vocabulary, and #10 fixed how the app is installed and launched. Every input this question was waiting on has landed, and #10 added the last few failure modes itself (launched at login with no target window resolved; a stale install path; a second instance).

It also absorbs the map's separate Detecting "not capturable" state fog. #2 established the mechanism (WGC most likely returns the last composited frame for a minimized or other-desktop window rather than erroring, so frame freshness can't be trusted and the app needs its own check such as IsIconic), and #9 established the stake (solving a stale frame spends real money on nothing, so it's a hard stop). What's left is not a separate mechanism question — it's the same policy-and-UX question as every other failure, and deciding it apart from the rest would produce two half-answers.

Decide:

• The failure taxonomy. What distinct failure states the app recognizes, and which of Provider seam design #5's error kinds (auth, refusal, transient-after-retry-exhausted) map onto which. Cost control #9's status pill already speaks throttled / paused (budget) / paused (runaway guard) — this decides what else it can say and whether that vocabulary needs to grow or stay small.
• Not-capturable detection and response. How the app decides the target window is minimized, on another virtual desktop, or otherwise not composing — IsIconic, frame-hash staleness, GraphicsCaptureItem.Closed, or a combination — and what it does: hard stop, slow-poll, or wait silently.
• Target window disappears. The window closes, or Configuration and API key storage #8's process-name-plus-title re-resolution fails on startup or mid-run. Configuration and API key storage #8 specified a fallback to reopening the picker on startup; this decides the mid-run case and whether an auto-recovered re-resolve is trustworthy enough to resume solving without asking.
• API and network failure. What the user sees when Provider seam design #5's internal retries are exhausted, when the key is rejected (auth), and when a stream dies mid-answer — including what happens to the half-rendered answer already in The output window #7's pane and to Cost control #9's usage accounting for the tokens that were burned but never reported.
• Bad or unusable frames. A black frame, a zero-size frame, a window resized to nothing. Whether these are detected before the money is spent, and how they differ from "captured fine, but there's no problem on screen."
• First-run and auto-start cold starts. Packaging and distribution #10 made auto-start opt-in and paused-on-launch; this decides what the app shows when it wakes at login with no API key entered, no target window resolvable, or a config file that fails to parse.
• How loud is loud enough. Silent, status-pill-only, in-pane message, or OS notification — per failure class. Cost control #9 established the silent → auto-recovering → sticky escalation ladder for budget limits; the question is whether failures share that ladder or need their own.

Deliverable: the failure taxonomy with, for each entry, the detection mechanism, the app's response, and the user-visible surface — expressed in #7's and #9's existing vocabulary wherever it already covers the case.

---

Generated by Claude Code