After an update

Use when an update finishes but the Gateway is down, channels are empty, or model calls fail with 401s.

apus status --all
apus update status --json
apus gateway status --deep
apus doctor --fix
apus gateway restart

Look for:

• Update restart in apus status / apus status --all. Pending or failed handoffs include the next command to run.
• plugin load failed: dependency tree corrupted; run apus doctor --fix under Channels: the channel config still exists, but plugin registration failed before the channel could load.
• Provider 401s after re-auth: apus doctor --fix checks for stale per-agent OAuth auth shadows and removes old copies so all agents resolve the current shared profile.

Prepared model runtime publication timeout

If startup reports prepared model runtime publication (...) timed out, the parenthesized detail identifies the pending stage and, during workspace preparation, its agent. Collect that error together with apus gateway status --deep and the startup logs.

An ambient credentials stage can be waiting for a plugin's external login check even when the Gateway process uses little CPU. For Claude CLI, run claude auth status --json as the Gateway user with the same environment. Startup shares this check across workspaces; a large roster should not launch one native-login subprocess per agent. A successful /health response alone does not establish that model runtime publication completed.

Split brain installs and newer config guard

Use when a gateway service unexpectedly stops after an update, or logs show one apus binary is older than the version that last wrote apus.json.

Apus stamps config writes with meta.lastTouchedVersion. Read-only commands can inspect a config written by a newer Apus, but process and service mutations refuse to run from an older binary. Blocked actions: gateway service start/stop/restart/uninstall, forced service reinstall, service-mode gateway startup, and gateway --force port cleanup.

which apus
apus --version
apus gateway status --deep
apus config get meta.lastTouchedVersion

Fix `PATH` so `apus` resolves to the newer install, then rerun the action.

Reinstall the intended gateway service from the newer install:

```bash
apus gateway install --force
apus gateway restart
```

Remove stale system package or old wrapper entries that still point at an old `apus` binary.

Protocol mismatch after rollback

Use when logs keep printing protocol mismatch after a downgrade or rollback. An older Gateway is running, but a newer local client process is still reconnecting with a protocol range the older Gateway cannot speak.

apus --version
which -a apus
apus gateway status --deep
apus doctor --deep
apus logs --follow

Look for:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in Gateway logs.
• Established clients: in apus gateway status --deep or Gateway clients in apus doctor --deep: active TCP clients connected to the Gateway port, with PIDs and command lines when the OS allows it.
• A client process whose command line points at the newer Apus install or wrapper you rolled back from.

Fix:

1. Stop or restart the stale Apus client process shown by gateway status --deep.
2. Restart apps or wrappers that embed Apus: local dashboards, editors, app-server helpers, or long-running apus logs --follow shells.
3. Re-run apus gateway status --deep or apus doctor --deep and confirm the stale client PID is gone.

Do not make an older Gateway accept a newer incompatible protocol. Protocol bumps protect the wire contract; rollback recovery is a process/version cleanup problem.