# Upgrade Guide — v0.17.3

<!-- bump: patch -->

## What Changed

### Per-Agent Shadow Installs — No More Global Pollution

The auto-updater previously used `npm install -g` to apply updates, which installed Instar globally on the machine. This caused version drift — all agents shared the same global binary regardless of when they were created or what version they expected. Agents installed via `npx instar` would silently start using a globally-installed version instead of their own.

Now each agent manages its own version independently:

1. **Shadow install directory**: Updates are installed to `{stateDir}/shadow-install/` — a local directory owned by each agent. No global npm modifications.

2. **Supervisor resolution**: On restart, the server supervisor checks for a shadow install first and uses it if present, falling back to the current binary only if no shadow exists.

3. **Rollback safety**: Rollbacks also use the shadow install pattern, so reverting to a previous version never touches global state.

4. **npx compatibility**: Agents started via `npx instar` continue to work normally. The shadow install only activates when the auto-updater applies an update — it never interferes with the initial launch mechanism.

### Removed npx Cache Workarounds

Previous versions had special logic to detect whether the agent was running from the npx cache and conditionally block auto-apply. This is no longer needed since updates go to the shadow directory, not the global prefix. The workaround code has been removed.

## What to Tell Your User

- **"Your agents no longer share versions."** Each agent now manages its own copy of Instar independently. Updating one agent never affects another. This prevents the version drift that was causing agents to run unexpected code.
- **"No more global installs."** Instar updates stay local to each agent. Your global npm is never modified, and agents started with npx continue to work exactly as before.
- **"Existing agents will self-heal."** The next time an agent auto-updates, it will use the new shadow install pattern automatically. No manual intervention needed.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Per-agent shadow installs | Automatic — no config needed |
| Independent version management | Each agent updates independently |
| Clean npx behavior | npx instar always downloads fresh, never picks up stale globals |
