docs: align supervised git update handoff docs

abnershang · abnershang · commit 50bafd3fc2fe · 2026-06-08T11:06:58.000+08:00
diff --git a/docs/cli/update.md b/docs/cli/update.md
@@ -124,21 +124,23 @@ When a local managed Gateway service is installed and restart is enabled,
 package-manager and git-checkout updates stop the running service before
 replacing the package tree or mutating the checkout/build output. The updater
 then refreshes the service metadata from the updated install, restarts the
-service, and verifies the restarted Gateway reports the expected version before
-reporting `Gateway: restarted and verified.`. 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 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. If restart cannot run, the command
-prints `Gateway: restart skipped (...)` or `Gateway: restart failed: ...` with a
-manual `openclaw gateway restart` hint. With `--no-restart`, package
-replacement or git rebuild still runs but the managed service is not stopped or
-restarted, so the running Gateway may keep old code until you restart it
-manually.
+service, and verifies the restarted Gateway before reporting
+`Gateway: restarted and verified.`. Package-manager updates additionally verify
+the restarted Gateway reports the expected package version; git-checkout updates
+verify gateway health and service readiness after the rebuild. 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 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. If restart
+cannot run, the command prints `Gateway: restart skipped (...)` or
+`Gateway: restart failed: ...` with a manual `openclaw gateway restart` hint.
+With `--no-restart`, package replacement or git rebuild still runs but the
+managed service is not stopped or restarted, so the running Gateway may keep old
+code until you restart it manually.
 
 ### Control-plane response shape
 
diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md
@@ -409,7 +409,7 @@ enumeration of `src/gateway/server-methods/*.ts`.
     - `config.apply` validates + replaces the full config payload.
     - `config.schema` returns the live config schema payload used by Control UI and CLI tooling: schema, `uiHints`, version, and generation metadata, including plugin + channel schema metadata when the runtime can load it. The schema includes field `title` / `description` metadata derived from the same labels and help text used by the UI, including nested object, wildcard, array-item, and `anyOf` / `oneOf` / `allOf` composition branches when matching field documentation exists.
     - `config.schema.lookup` returns a path-scoped lookup payload for one config path: normalized path, a shallow schema node, matched hint + `hintPath`, optional `reloadKind`, and immediate child summaries for UI/CLI drill-down. `reloadKind` is one of `restart`, `hot`, or `none` and mirrors the Gateway config reload planner for the requested path. Lookup schema nodes keep the user-facing docs and common validation fields (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, numeric/string/array/object bounds, and flags like `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Child summaries expose `key`, normalized `path`, `type`, `required`, `hasChildren`, optional `reloadKind`, plus the matched `hint` / `hintPath`.
-    - `update.run` runs the gateway update flow and schedules a restart only when the update itself succeeded; callers with a session can include `continuationMessage` so startup resumes one follow-up agent turn through the restart continuation queue. Package-manager updates from the control plane use a detached managed-service handoff instead of replacing the package tree inside the live Gateway. A started handoff returns `ok: true` with `result.reason: "managed-service-handoff-started"` and `handoff.status: "started"`; unavailable or failed handoffs return `ok: false` with `managed-service-handoff-unavailable` or `managed-service-handoff-failed`, plus `handoff.command` when a manual shell update is required. During a started handoff, the restart sentinel may briefly report `stats.reason: "restart-health-pending"`; the continuation is delayed until the CLI verifies the restarted Gateway and writes the final `ok` sentinel.
+    - `update.run` runs the gateway update flow and schedules a restart only when the update itself succeeded; callers with a session can include `continuationMessage` so startup resumes one follow-up agent turn through the restart continuation queue. Package-manager updates and supervised git-checkout updates from the control plane use a detached managed-service handoff instead of replacing the package tree or mutating checkout/build output inside the live Gateway. A started handoff returns `ok: true` with `result.reason: "managed-service-handoff-started"` and `handoff.status: "started"`; unavailable or failed handoffs return `ok: false` with `managed-service-handoff-unavailable` or `managed-service-handoff-failed`, plus `handoff.command` when a manual shell update is required. During a started handoff, the restart sentinel may briefly report `stats.reason: "restart-health-pending"`; the continuation is delayed until the CLI verifies the restarted Gateway and writes the final `ok` sentinel.
     - `update.status` returns the latest cached update restart sentinel, including the post-restart running version when available.
     - `wizard.start`, `wizard.next`, `wizard.status`, and `wizard.cancel` expose the onboarding wizard over WS RPC.
 
