# Instar Upgrade Guide — NEXT

<!-- bump: patch -->

## What Changed

**`instar join` now installs auto-start for the joined home (mesh bootstrap fix).**
Previously a joined mesh agent had no LaunchAgent/systemd unit, so it never
auto-started — and a stale auto-start entry from a prior `instar init` of the same
name (at a different directory) would keep respawning a server against the WRONG
home, fighting the joined one for the port. join now installs auto-start for its
own home; because the unit is keyed on the agent name, this cleanly replaces any
stale same-name unit. One unit, pointing at the right home.

## What to Tell Your User

- Joining a second machine to your agent's mesh now "just works" for staying alive
  across reboots — the joined machine sets up its own background auto-start, and it
  won't collide with leftovers from an earlier setup attempt of the same agent. You
  no longer have to hand-start the joined agent or manually clean up a stale startup
  entry.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| join installs auto-start | Automatic — `instar join` now registers the joined home's background auto-start (LaunchAgent on macOS, systemd on Linux), replacing any stale same-name unit. |

## Evidence

**Small, contained join-flow addition; no change to init.** Unit test
`tests/unit/init-join-launchd-handoff.test.ts` (2 cases, darwin-gated, sandboxed
$HOME) proves the Label-keyed replace: two installs for the same name + different
dirs leave ONE plist pointing at the second (joined) dir; standby install writes
server-start (not lifeline) args. `tsc --noEmit` clean. The autostart install is
try/catch-wrapped so a failure never fails the join. Side-effects review:
`upgrades/side-effects/init-join-launchagent-handoff.md`. Spec: Track C of
`docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md`.
