Start with the message or status visible in Desktop. Each symptom points to a different check, while restarting everything at once can hide the original problem.
| Symptom | Check first | Safe next action |
|---|---|---|
| Provider required or credential required | Selected provider, API key, or local endpoint | Complete provider setup and run a short test |
| Runtime never becomes ready | Desktop diagnostics and Local Core status | Preserve logs, then restart Local Core from the supported control |
| Managed database is unhealthy | Database status in diagnostics | Use the documented database recovery action; do not delete application data |
| Workspace is missing | Folder exists and Desktop still has permission | Re-add the folder through the project picker |
| Session will not continue | Last terminal status and waiting reason | Use operator control or recovery on the same session |
| Application will not open | macOS version, architecture, checksum, Gatekeeper, and LaunchServices message | Re-download the signed DMG; do not disable system security globally |
| Model is saved but unavailable | Provider reachability, model ID, capability qualification, and policy | Repair the owning provider state; do not select an unverified fallback |
| Manual upgrade reports the wrong version | Applications copy, release checksum, and running process identity | Quit Kestrel and reinstall the exact signed 0.8.6 application |
Application and LaunchServices
Verify macOS 13+, Apple silicon, the release checksum, Developer ID signature, notarization, and that the application running from Applications is the 0.8.6 copy.
Local Core
Inspect health, build identity, readiness reason, supervised process state, and content-aware restart. Preserve socket and process evidence before restarting the owned component.
Providers
Check credential presence, endpoint reachability, exact model identity, registry capabilities, qualification, authority, and budget. These failures are not application launch failures.
Projects
Check folder existence and permissions, project registration, Git/worktree preparation, workspace readiness, and durable run-subscription cursor.
Manual updates
Check the Desktop release, checksum, signing identity, installed application version, preserved project library, and Local Core migrations. Do not clear state to make a version mismatch disappear.
Collect evidence
Capture visible status, Desktop and Local Core version/build identity, platform, project/session identifiers, exact timestamps, recent logs, terminal outcome, and support bundle. Review for secrets before sharing.
Confirm the fix
Return to the original workspace and session, then run a small request. A recovery is complete only when the affected status clears and the existing history remains usable.
If the symptom persists, capture the visible status, Desktop version, platform, and the smallest repeatable sequence before reporting an issue.