| 1 | # Recovery and diagnostics (v1.20+) |
| 2 | |
| 3 | Reasonix no longer ships a product `reasonix-guard` recovery shell. Crash |
| 4 | records, pending-update state, and configuration problems do not change the |
| 5 | next launch into a global Safe Mode. |
| 6 | |
| 7 | ## Prefer these tools |
| 8 | |
| 9 | ```text |
| 10 | reasonix doctor |
| 11 | reasonix doctor repair |
| 12 | reasonix crash report # when available in your build |
| 13 | ``` |
| 14 | |
| 15 | - **doctor** inspects configuration, derived desktop state, and common install |
| 16 | problems without loading the desktop shell. |
| 17 | - **doctor repair** applies safe, explicit repairs the user opts into. |
| 18 | - Crash reports remain opt-in and never force a degraded product mode. |
| 19 | |
| 20 | ## When a conversation cannot continue |
| 21 | |
| 22 | In `transcript gate ... at message N`, `N` is an index in the model request, |
| 23 | not the user's message number. Keep the complete error for diagnosis. |
| 24 | |
| 25 | - Invalid tool arguments are recovered using recorded execution evidence. |
| 26 | Calls that cannot be safely reconstructed become historical records for the |
| 27 | model. Original arguments, results and chat history stay intact; recovery |
| 28 | never executes the tools again. |
| 29 | - Missing or damaged local images from earlier turns are marked unavailable; |
| 30 | text and remaining usable images continue. The model is told to request a |
| 31 | replacement if needed. A failed image in the current turn must be reattached. |
| 32 | - Invalid requests from optional extensions are skipped. Required extensions |
| 33 | and explicit blocking decisions still pause the operation with guidance. |
| 34 | - Context preparation has one five-minute generation budget, including queued |
| 35 | and chunked work. Heartbeats do not extend it. A failed summary keeps the last |
| 36 | committed context; it no longer triggers additional lossy truncation. If that |
| 37 | context cannot be sent safely, the current attempt stops with a recoverable |
| 38 | error. Retry with `/compact`, shorten the latest message, or select a model |
| 39 | with a larger context window. Original chat history stays available. |
| 40 | - On save failures, keep the conversation open, export a backup if available, |
| 41 | and check disk space and write permissions. Model requests and tool execution |
| 42 | remain paused until the required save has been confirmed. |
| 43 | |
| 44 | These recovery paths do not require deleting chat history or editing session |
| 45 | files. Derived recovery caches are rebuilt when needed. |
| 46 | |
| 47 | ## Install layout (v1.20+) |
| 48 | |
| 49 | Windows and Linux use a versioned install root: |
| 50 | |
| 51 | ```text |
| 52 | InstallRoot/ |
| 53 | reasonix-launcher[.exe] |
| 54 | Reasonix.exe # Windows portable / Start Menu alias |
| 55 | reasonix[-cli.exe] |
| 56 | current.json |
| 57 | versions/<version>/ |
| 58 | reasonix-desktop[.exe] |
| 59 | reasonix-cli[.exe] |
| 60 | reasonix-update-helper[.exe] |
| 61 | ``` |
| 62 | |
| 63 | The thin launcher only reads `current.json` and starts the active desktop. It |
| 64 | never selects a previous version or enters Safe Mode. |
| 65 | |
| 66 | ## Upgrading from 1.18–1.19.x |
| 67 | |
| 68 | If an older client is stuck on a pending update or Safe Mode loop: |
| 69 | |
| 70 | 1. Download the latest signed installer / package from the official download page. |
| 71 | 2. Install it directly over the current copy (Windows: double-click; macOS: |
| 72 | replace `Reasonix.app`). Do not uninstall first: keeping the existing install |
| 73 | root lets the compatibility migrator prove which stale transaction it owns. |
| 74 | 3. Start Reasonix once and confirm **Settings > Updates** shows the installed |
| 75 | version before trying another in-app update. |
| 76 | 4. Compatibility payloads may still include a one-shot binary named |
| 77 | `reasonix-guard` that only migrates the flat layout into `current.json` and |
| 78 | then deletes itself. That binary is not the old Guard product. |
| 79 | |
| 80 | Do not manually delete `pending-update.json`, locks, or AppData as the recovery |
| 81 | procedure. |
| 82 | |
| 83 | ## In-app update stuck |
| 84 | |
| 85 | If Settings → Updates (or the top banner) reports that the previous update has |
| 86 | not finished (`pending update already exists`, `awaiting startup health`, or |
| 87 | `handoff backup` errors): |
| 88 | |
| 89 | 1. Click **Discard previous update** in the banner or Settings, then **Retry**. |
| 90 | 2. If that button is missing or fails, quit Reasonix fully and start it once so |
| 91 | startup can commit or retire the probationary transaction, then retry the |
| 92 | in-app update. |
| 93 | 3. If in-app update still fails, download the latest signed installer from the |
| 94 | official download page and install it **over** the current copy without |
| 95 | uninstalling first. |
| 96 | 4. On macOS, also allow Reasonix under System Settings → Privacy & Security → |
| 97 | App Management when the dialog appears; a leftover |
| 98 | `Reasonix.app.reasonix-update-backup` that TCC will not let the app remove |
| 99 | may still require the official installer path. |
| 100 | |
| 101 | If the Windows installer reports `Reasonix layout activation failed`, expand |
| 102 | the installer details and copy the lines under `Reasonix layout activator |
| 103 | output:`. Current installers preserve the activator's concrete error instead of |
| 104 | showing only exit code 1. |
| 105 | |
| 106 | ## macOS |
| 107 | |
| 108 | macOS keeps LaunchServices launching the desktop app bundle directly. Updates |
| 109 | replace the signed `.app` atomically; there is no Guard process. |
| 110 | |
| 111 | After the replacement window becomes visible, Reasonix commits only the exact |
| 112 | pending transaction captured before launch. Legacy transactions that lack a |
| 113 | backup digest, or whose backup is already gone, are retired automatically only |
| 114 | after the running executable is proven to belong to that target bundle. Any |
| 115 | surviving unknown backup and the original transaction are archived for recovery; |
| 116 | they are not deleted or trusted as an automatic rollback source. |
| 117 |