# Upgrade Guide — v0.28.2

<!-- bump: patch -->

## What Changed

**Lifeline Shutdown Crash-Proofing** — The shutdown handler in both the lifeline and server now wraps `unregisterAgent`, `stopHeartbeat`, and other cleanup steps in try-catch. Previously, an ELOCKED error from the agent registry during SIGTERM would crash the lifeline with an unhandled exception. This confused launchd's KeepAlive restart logic and could leave the agent in a "spawn scheduled" limbo state indefinitely. The lifeline also now installs global `uncaughtException` and `unhandledRejection` handlers that specifically catch ELOCKED errors — the lifeline will never crash from registry lock contention again.

**409 Conflict Resolution** — When a stale Telegram long-poll connection causes persistent 409 Conflict errors ("another bot instance is polling"), the lifeline now actively tries to reclaim exclusive polling every 20 failures by calling deleteWebhook followed by a zero-timeout getUpdates. Previously, the lifeline would back off to 60 seconds and never recover, rendering the agent permanently unreachable until a manual restart.

**Settings JSON Self-Healing** — Both the lifeline startup and the ServerSupervisor preflight checks now validate `.claude/settings.json` for parseable JSON. If unresolved git merge conflict markers are detected, the file is auto-repaired by stripping the conflict markers (with a backup saved). This was the root cause of a complete agent outage where every Claude Code session crashed on startup due to invalid JSON, while the lifeline and server showed no errors — the agent appeared alive but never responded to messages.

## What to Tell Your User

- **More resilient agent recovery**: "Your agent is now much harder to take down. Even if something goes wrong during a restart, the lifeline will survive and keep your agent reachable. Previously, a lock file contention during shutdown could permanently strand the agent."

- **Automatic Telegram recovery**: "If your agent's Telegram connection gets into a conflict state — for example after a machine sleep or a crash — it will now automatically recover instead of requiring a manual restart."

- **Config corruption protection**: "If a git sync causes a merge conflict in your agent's settings file, the system will now detect and auto-repair it. Previously, this could silently prevent all sessions from starting while everything else appeared healthy."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Shutdown crash-proofing | Automatic — ELOCKED errors during shutdown are caught and logged |
| 409 conflict resolution | Automatic — reclaim attempt every 20 consecutive 409 errors |
| Settings JSON validation | Automatic — preflight check on every server/lifeline start |
| Global ELOCKED safety net | Automatic — uncaught ELOCKED errors logged but don't crash lifeline |

