# Upgrade Guide — v0.26.3

<!-- bump: patch -->

## What Changed

Three reliability fixes that prevent the cascade failure where a native module mismatch crashes the entire server process:

1. **FeatureRegistry graceful degradation** — Previously, if better-sqlite3 failed to load (e.g., after a Node.js version upgrade), `FeatureRegistry.open()` threw an unhandled error that crashed the entire server process. Now it catches the error, reports a degradation, and the server continues running with in-memory-only feature definitions. This was the direct cause of sagemind's crash-loop — the server would start, initialize most subsystems, then crash at FeatureRegistry.

2. **Preflight native module rebuild** — The ServerSupervisor's preflight self-heal now detects better-sqlite3 native module version mismatches before spawning the server. If the module was compiled for a different Node version, it runs `npm rebuild better-sqlite3` automatically. This catches the problem before it can cause a crash.

3. **Smarter post-rebase pull strategy** — When git-sync detects and aborts a stuck rebase, it now uses a merge pull instead of another rebase pull. Previously, aborting a stuck rebase and immediately doing `git pull --rebase` would recreate the exact same conflict, putting the repo right back in a stuck state. Using `--no-rebase` after a recovery avoids this loop.

## What to Tell Your User

- "Your agents are now much more resilient to Node.js version changes. Previously, upgrading Node (even via a routine brew upgrade) could put an agent into a crash loop that required manual intervention. Now the server gracefully handles the mismatch and the supervisor automatically rebuilds the affected modules."
- "Git sync is also smarter about recovering from conflicts — it won't keep retrying the same failing strategy."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| FeatureRegistry crash protection | Automatic — server survives sqlite3 failures |
| Native module auto-rebuild | Automatic — preflight detects and fixes mismatches |
| Post-rebase merge fallback | Automatic — git-sync uses merge after rebase recovery |
