Document deferred OpenCode restart contract and drop dead helper.

Add config-mutation-response.js to owning docs, describe restartDeferred
and external requiresManualRestart on /api/config/reload, and remove the
unused buildConfigMutationResponse export.

Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>

packages/web/server/lib/opencode/DOCUMENTATION.md

@@ -17,7 +17,8 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/bootstrap-runtime.js`: base app bootstrap runtime for status/auth/tts/notification/OpenChamber route wiring.
 - `packages/web/server/lib/opencode/network-runtime.js`: OpenCode URL construction, health-probe readiness checks, and API prefix runtime.
 - `packages/web/server/lib/opencode/project-directory-runtime.js`: request-scoped and settings-backed project directory resolution/validation runtime.
-- `packages/web/server/lib/opencode/config-entity-routes.js`: route registration for agent/command/MCP config orchestration and reload semantics.
+- `packages/web/server/lib/opencode/config-entity-routes.js`: route registration for agent/command/MCP config orchestration with deferred-apply semantics (`restartDeferred` payloads; explicit apply via `POST /api/config/reload`).
+- `packages/web/server/lib/opencode/config-mutation-response.js`: shared response builders for deferred OpenCode restarts and external manual-restart guidance.
 - `packages/web/server/lib/opencode/snippets.js`: opencode-snippets-compatible snippet file CRUD, discovery, and hashtag expansion.
 - `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
 - `packages/web/server/lib/opencode/core-routes.js`: server status/system routes, auth/access guard routes, and settings utility route registration.
@@ -233,6 +234,11 @@ Transport-triggered health checks share the periodic monitor's failure accountin
   - Commands: `/api/config/commands/:name`
   - MCP servers: `/api/config/mcp` and `/api/config/mcp/:name`
   - Snippets: `/api/config/snippets`, `/api/config/snippets/:name`, and `/api/config/snippets/expand`
+- Agent/command/MCP write routes persist config to disk and return a deferred-restart payload (`requiresReload: false`, `requiresRestart: true`, `restartDeferred: true`) instead of restarting OpenCode immediately. The UI accumulates these changes and applies them with `POST /api/config/reload`.
+
+## Public exports (config-mutation-response.js)
+- `buildDeferredRestartResponse(message)`: success payload for config mutations that are saved on disk but waiting for an explicit Apply & Restart (`restartDeferred: true`).
+- `buildExternalManualRestartResponse(message)`: success payload when OpenCode is an external process and the operator must restart it manually (`requiresManualRestart: true`).
 
 ## Public exports (auth-state-runtime.js)
 - `createOpenCodeAuthStateRuntime(dependencies)`: creates runtime for managed OpenCode auth password state and request headers.
@@ -262,7 +268,7 @@ Transport-triggered health checks share the periodic monitor's failure accountin
    - `app.use('/api', ...)` auth/tunnel guard
 - `registerSettingsUtilityRoutes(app, dependencies)`: registers small settings utility endpoints:
   - `GET /api/config/themes`
-  - `POST /api/config/reload`
+  - `POST /api/config/reload` — applies accumulated deferred OpenCode config changes. Managed OpenCode restarts and returns `requiresReload: true`. External OpenCode returns `requiresManualRestart: true` (changes are already on disk; the connected server must be restarted outside OpenChamber).
 - `registerCommonRequestMiddleware(app, dependencies)`: registers shared request middleware stack:
   - conditional JSON body parser behavior for `/api/*` vs non-API requests
   - URL-encoded parser setup

packages/web/server/lib/opencode/config-mutation-response.js

@@ -24,21 +24,3 @@ export function buildExternalManualRestartResponse(message) {
     message,
   };
 }
-
-export function buildConfigMutationResponse(refreshResult, { liveMessage, manualRestartMessage, deferredMessage }) {
-  if (refreshResult && refreshResult.external) {
-    return buildExternalManualRestartResponse(manualRestartMessage);
-  }
-
-  // When callers skip the live refresh (deferred apply flow), report a pending restart.
-  if (!refreshResult || refreshResult.deferred === true) {
-    return buildDeferredRestartResponse(deferredMessage || liveMessage);
-  }
-
-  return {
-    success: true,
-    requiresReload: true,
-    message: liveMessage,
-    reloadDelayMs: refreshResult.reloadDelayMs,
-  };
-}