| 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 | ## Install layout (v1.20+) |
| 21 | |
| 22 | Windows and Linux use a versioned install root: |
| 23 | |
| 24 | ```text |
| 25 | InstallRoot/ |
| 26 | reasonix-launcher[.exe] |
| 27 | Reasonix.exe # Windows portable / Start Menu alias |
| 28 | reasonix[-cli.exe] |
| 29 | current.json |
| 30 | versions/<version>/ |
| 31 | reasonix-desktop[.exe] |
| 32 | reasonix-cli[.exe] |
| 33 | reasonix-update-helper[.exe] |
| 34 | ``` |
| 35 | |
| 36 | The thin launcher only reads `current.json` and starts the active desktop. It |
| 37 | never selects a previous version or enters Safe Mode. |
| 38 | |
| 39 | ## Upgrading from 1.18–1.19.x |
| 40 | |
| 41 | If an older client is stuck on a pending update or Safe Mode loop: |
| 42 | |
| 43 | 1. Download the latest signed installer / package from the official download page. |
| 44 | 2. Install it directly over the current copy (Windows: double-click; macOS: |
| 45 | replace `Reasonix.app`). Do not uninstall first: keeping the existing install |
| 46 | root lets the compatibility migrator prove which stale transaction it owns. |
| 47 | 3. Start Reasonix once and confirm **Settings > Updates** shows the installed |
| 48 | version before trying another in-app update. |
| 49 | 4. Compatibility payloads may still include a one-shot binary named |
| 50 | `reasonix-guard` that only migrates the flat layout into `current.json` and |
| 51 | then deletes itself. That binary is not the old Guard product. |
| 52 | |
| 53 | Do not manually delete `pending-update.json`, locks, or AppData as the recovery |
| 54 | procedure. |
| 55 | |
| 56 | ## In-app update stuck |
| 57 | |
| 58 | If Settings → Updates (or the top banner) reports that the previous update has |
| 59 | not finished (`pending update already exists`, `awaiting startup health`, or |
| 60 | `handoff backup` errors): |
| 61 | |
| 62 | 1. Click **Discard previous update** in the banner or Settings, then **Retry**. |
| 63 | 2. If that button is missing or fails, quit Reasonix fully and start it once so |
| 64 | startup can commit or retire the probationary transaction, then retry the |
| 65 | in-app update. |
| 66 | 3. If in-app update still fails, download the latest signed installer from the |
| 67 | official download page and install it **over** the current copy without |
| 68 | uninstalling first. |
| 69 | 4. On macOS, also allow Reasonix under System Settings → Privacy & Security → |
| 70 | App Management when the dialog appears; a leftover |
| 71 | `Reasonix.app.reasonix-update-backup` that TCC will not let the app remove |
| 72 | may still require the official installer path. |
| 73 | |
| 74 | If the Windows installer reports `Reasonix layout activation failed`, expand |
| 75 | the installer details and copy the lines under `Reasonix layout activator |
| 76 | output:`. Current installers preserve the activator's concrete error instead of |
| 77 | showing only exit code 1. |
| 78 | |
| 79 | ## macOS |
| 80 | |
| 81 | macOS keeps LaunchServices launching the desktop app bundle directly. Updates |
| 82 | replace the signed `.app` atomically; there is no Guard process. |
| 83 | |
| 84 | After the replacement window becomes visible, Reasonix commits only the exact |
| 85 | pending transaction captured before launch. Legacy transactions that lack a |
| 86 | backup digest, or whose backup is already gone, are retired automatically only |
| 87 | after the running executable is proven to belong to that target bundle. Any |
| 88 | surviving unknown backup and the original transaction are archived for recovery; |
| 89 | they are not deleted or trusted as an automatic rollback source. |
| 90 |