# Upgrade Guide — v0.12.29

<!-- bump: patch -->

## What Changed

### WhatsApp Baileys Robustness (preventing 405 errors)

1. **Dynamic WA Web version fetching**: `BaileysBackend.connect()` now calls `fetchLatestWaWebVersion()` from Baileys before creating the socket. This prevents 405 (Method Not Allowed) errors caused by stale hardcoded protocol versions. Falls back gracefully to Baileys defaults if the fetch fails.

2. **Platform identifier fix**: The browser config now defaults to `['Mac OS', 'Chrome', '14.4.1']` which maps to `Platform.MACOS`. Some Baileys versions defaulted to `Platform.WEB` which WhatsApp servers reject for new device pairing.

3. **User-configurable overrides**: New `version` and `browser` fields in `BaileysConfig` allow users to override the protocol version and platform identifier without patching Baileys files. Set via `config.json` under the WhatsApp messaging config or nested `baileys` key.

### Config.json backup protection

Before running post-update migrations on server startup, `config.json` is now backed up to `config.json.backup`. This protects against accidental data loss if a migration or re-scaffold operation wipes the config.

### Server restart command

New `instar server restart [name]` command that handles service manager lifecycle correctly:
- **macOS**: Uses `launchctl bootout` + `bootstrap` to properly cycle the launchd service
- **Linux**: Uses `systemctl --user restart` for systemd
- **No autostart**: Falls back to `stop` + `start`

This solves the debugging problem where killing a launchd-managed server just caused it to respawn with the old code.

## What to Tell Your User

- **WhatsApp reliability**: "WhatsApp connections are now more resilient. The system automatically fetches the latest protocol version instead of relying on a hardcoded one that can go stale. This prevents the 405 connection failures we hit."
- **Server restart**: "There's now an `instar server restart` command that handles launchd properly. No more zombie respawns when you need to restart with new code."
- **Config safety**: "Your config.json is now backed up before any upgrade migration runs, so you won't lose your settings if something goes wrong."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Dynamic WA version fetch | Automatic — happens on every WhatsApp connect |
| Custom WA version override | Set `version: [2, 3000, XXXXXXX]` in WhatsApp config |
| Custom browser/platform override | Set `browser: ["Mac OS", "Chrome", "14.4.1"]` in WhatsApp config |
| Server restart | `instar server restart [agent-name]` |
| Config backup | Automatic — happens before post-update migration |
