docs: record upgrade recovery fixes

CHANGELOG.md

@@ -37,6 +37,7 @@ Docs: https://docs.openclaw.ai
 - Agents/network: allow trusted web-search providers and configured model-provider hosts to work behind Surge/Clash/sing-box fake-IP DNS by accepting RFC 2544 and IPv6 ULA synthetic answers only for the request's scoped hostname, without broad private-network access. Refs #76530 and #76549. Thanks @zqchris.
 - Providers: honor env-proxy settings for guarded provider model fetches when no explicit dispatcher policy is configured, preserving explicit transport overrides. Fixes #70453. (#72480) Thanks @mjamiv.
 - Feishu: accept and honor `channels.feishu.blockStreaming` at the top level and per account, while keeping the legacy default off so Feishu cards no longer reject documented config or silently drop block replies. Fixes #75555. Thanks @vincentkoc.
+- Gateway/update: avoid `launchctl kickstart -k` immediately after fresh macOS update bootstraps, and remove dangling global plugin-runtime symlinks during packaged postinstall and `doctor --fix` so upgrades no longer SIGTERM the newly booted Gateway or leave bundled plugin imports pointed at pruned `plugin-runtime-deps` trees. Completes #76261 and fixes #76466. (#76929)
 - Google Chat: normalize custom Google auth transport headers before google-auth/gaxios interceptors run, restoring webhook token verification when certificate retrieval expects Fetch `Headers`. Fixes #76742. Thanks @donbowman.
 - Doctor/plugins: reset stale `plugins.slots.memory` and `plugins.slots.contextEngine` references during `doctor --fix`, so cleanup of missing plugin config does not leave unrecoverable slot owners behind. Fixes #76550 and #76551. Thanks @vincentkoc.
 - Docs/WhatsApp: merge the duplicate top-level `web` objects in the gateway channel config example so copy-pasted WhatsApp config keeps both `web.whatsapp` and reconnect settings. Fixes #76619. Thanks @WadydX.

docs/cli/update.md

@@ -116,10 +116,12 @@ service, and verify the restarted Gateway reports the expected version before
 reporting success. On macOS, the post-update check also verifies the LaunchAgent
 is loaded/running for the active profile and the configured loopback port is
 healthy. If the plist is installed but launchd is not supervising it, OpenClaw
-re-bootstraps and kickstarts the LaunchAgent automatically, then reruns the
-health/version/channel readiness checks. If the Gateway still does not become
-healthy, the command exits non-zero and prints the restart log path plus explicit
-restart, reinstall, and package rollback instructions. With `--no-restart`,
+re-bootstraps the LaunchAgent automatically, then reruns the
+health/version/channel readiness checks. A fresh bootstrap loads the RunAtLoad
+job directly, so update recovery does not immediately `kickstart -k` the newly
+spawned Gateway. If the Gateway still does not become healthy, the command exits
+non-zero and prints the restart log path plus explicit restart, reinstall, and
+package rollback instructions. With `--no-restart`,
 package replacement still runs but the managed service is not stopped or
 restarted, so the running Gateway may keep old code until you restart it
 manually.

docs/plugins/dependency-resolution.md

@@ -118,8 +118,11 @@ not a supported way to prepare bundled plugin dependencies.
 
 Older OpenClaw versions generated bundled-plugin dependency roots at startup or
 during doctor repair. Current doctor cleanup removes those stale directories and
-symlinks when `--fix` is used, including old `plugin-runtime-deps` roots,
+symlinks when `--fix` is used, including old `plugin-runtime-deps` roots, global
+Node-prefix package symlinks that point at pruned `plugin-runtime-deps` targets,
 `.openclaw-runtime-deps*` manifests, generated plugin `node_modules`, install
-stage directories, and package-local pnpm stores.
+stage directories, and package-local pnpm stores. Packaged postinstall also
+removes those global symlinks before pruning the legacy target roots so upgrades
+do not leave dangling ESM package imports.
 
 These paths are legacy debris only. New installs should not create them.