# 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.

## 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.

Rollback is never automatic. Major-version rollback remains blocked unless the
snapshot is explicitly marked rollback safe.