# Lumi Recovery Mode

Failed updates should leave an administrator with a recovery path. Lumi writes a
recovery marker before update files are applied and keeps snapshots available for
manual revert. If an update throws after replacement begins, Lumi first attempts
to restore the new snapshot automatically. Failed automatic restoration keeps
the backup and records both errors for safe-mode recovery.

## Recovery Marker

The marker lives at `data/recovery/update-marker.json` and records:

- target kind and id
- from/to versions
- source branch
- update method
- rollback safety
- snapshot id when available
- status and timestamps

Statuses include `pending`, `applying`, `verifying`, `completed`, `failed`, and
`stale`. A completed marker is cleared after a successful normal startup. If
Lumi starts and finds an incomplete marker, it marks it stale so the admin UI and
safe-mode UI can show the last attempted update.

## Manual Safe Mode

Safe mode can be started with any of these triggers:

```bash
LUMI_SAFE_MODE=1 npm run run
node run.js --safe-mode
```

Creating `data/recovery/safe-mode.flag` also makes the wrapper start
`safe-mode.js` instead of the full bot. Safe mode loads only the minimum services
needed for recovery: config/database, auth/session, static recovery UI,
snapshots/revert, plugin disable, and restart controls. Optional plugins,
platform clients, AI runtime, scheduled jobs, and non-essential integrations are
not loaded.

## Admin Recovery UI

The normal **Admin > Updates** page shows a recovery banner when a marker is
present. The standalone safe-mode page shows the last attempted target, versions,
method, source branch, snapshot id, timestamp, and error.

Admins can:

- revert a safe snapshot,
- disable a problematic plugin,
- clear a stale marker after verifying startup,
- retry normal startup.

The normal Updates page submits these actions through the shared timed
confirmation and request contracts. When an action restarts Lumi, the current
document remains open and reconnects before refreshing recovery status in place.

Manual major-version rollback remains blocked unless the snapshot is explicitly
marked rollback safe. The automatic rollback attempted for the same failed
update is allowed because it restores the immediately preceding state.
