---
name: upgrade
description: "Upgrade Real Agent to the latest published version by re-running the brand's installer when the operator asks."
---

# Upgrade

Invoked by the admin agent directly.

The operator wants to upgrade Real Agent. Re-run the installer for the active brand; it is idempotent, brings the install to the latest published version, and restarts the brand service when it finishes.

## Resolve the brand package

The package to install is `npm.packageName` in `$PLATFORM_ROOT/config/brand.json`. Read that field with `Read`. Never hard-code a default — operators install branded variants and the field is the source of truth.

## Run the upgrade

```
npx -y <npm.packageName>@latest
```

Stream the installer's stdout to the operator as it runs. The installer prints its own progress; pass it through, do not narrate around it.

The brand service restarts as the installer's last step, which terminates this Bash invocation before the installer's final line prints. That is the expected contract, not a failure. Tell the operator the connection will drop and to reconnect.

## Confirm on the next session

The next session's reconnaissance reads `$PLATFORM_ROOT/config/.${hostname}-version` (with `hostname` from `brand.json`) and finds the new value. Lead the next session with one short sentence: "Upgraded to vX.Y.Z." If that file is unchanged after a fresh reconnaissance, the installer failed; show the last stdout lines captured before the restart and stop.

## Surface failures verbatim

- npx fetch from `registry.npmjs.org` fails (network, DNS, registry outage): show the error to the operator.
- Installer exits non-zero before the restart: show the tail of stdout and stop.
- `Permission denied` on `npx`: Bash scope is misconfigured for this install; tell the operator.

Never claim success on a failed run.