# Upgrade Guide: Robust Auto-Restart

## What Changed

### Auto-Restart Never Asks Users to Run Commands

Previously, when an update was installed but the running binary didn't pick up the change (common with npx cache, local installs, or PATH issues), the agent would send a message like "Please restart me from the global binary: instar server start --foreground." This violated the principle that agents should never ask users to run commands.

Now the auto-updater has a 5-strategy binary resolution pipeline that finds the correct binary in virtually all environments:

1. `npm bin -g` — the actual global bin directory npm writes to
2. `which instar` — PATH lookup (excludes npx cache and local node_modules)
3. `npm prefix -g` + `/bin/instar` — prefix-based lookup
4. `npm root -g` + `/instar/dist/cli.js` — direct module entry point (bypasses bin symlink)
5. `process.argv` fallback — only if not from a stale source

If all strategies fail, the agent logs the issue and continues running rather than asking the user for help.

### Service Manager Detection

Agents running under launchd (macOS) or systemd (Linux) now detect their process manager and let it handle restarts. Instead of spawning a replacement process, they simply exit cleanly — the service manager restarts them from the updated binary automatically.

### Loop Guard Recovery

When the restart loop guard detects that a previous restart loaded a stale binary, it now attempts one more restart with aggressive path resolution instead of giving up and messaging the user.

## What to Tell Your User

- **Invisible updates**: "Updates now happen completely in the background. You'll never see a message asking you to restart me or run a command. I handle it all automatically."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| 5-strategy binary resolution | Automatic — finds the correct binary path in any install environment |
| Service manager detection | Automatic — launchd/systemd managed agents let the manager handle restart |
| Loop guard recovery | Automatic — retries with better path resolution instead of giving up |
