docs: document gateway runtime startup

src/gateway/server-plugin-bootstrap.ts

@@ -1,3 +1,5 @@
+// Gateway plugin bootstrap helpers.
+// Applies activation config, installs runtime bindings, loads and pins plugins.
 import { primeConfiguredBindingRegistry } from "../channels/plugins/binding-registry.js";
 import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/gateway/server-runtime-config.ts

@@ -1,3 +1,5 @@
+// Gateway startup runtime-config resolver.
+// Normalizes bind/auth/HTTP/Tailscale/hook settings before server construction.
 import type {
   GatewayAuthConfig,
   GatewayBindMode,

src/gateway/server-runtime-handles.ts

@@ -1,3 +1,5 @@
+// Gateway mutable runtime handles.
+// Provides stop-safe defaults for timers, sidecars, subscriptions, and services.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { HeartbeatRunner } from "../infra/heartbeat-runner.js";
 import type { ChannelHealthMonitor } from "./channel-health-monitor.js";
@@ -37,6 +39,8 @@ export type GatewayServerMutableState = {
 /** Creates gateway mutable state with inert handles that are safe to stop before startup finishes. */
 export function createGatewayServerMutableState(): GatewayServerMutableState {
   const noopInterval = () => {
+    // Dummy unref'd timers give shutdown code a concrete handle to clear even
+    // when startup exits before real maintenance intervals are installed.
     const timer = setInterval(() => {}, 1 << 30);
     timer.unref?.();
     return timer;

src/gateway/server-runtime-services.ts

@@ -1,3 +1,5 @@
+// Gateway post-ready runtime services.
+// Starts delayed maintenance, cron, heartbeat, recovery, and pricing refresh work.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { isVitestRuntimeEnv } from "../infra/env.js";
 import { startHeartbeatRunner, type HeartbeatRunner } from "../infra/heartbeat-runner.js";
@@ -35,6 +37,8 @@ function clearGatewayMaintenanceHandles(maintenance: GatewayMaintenanceHandles |
   if (!maintenance) {
     return;
   }
+  // Maintenance startup can race shutdown. Clear every interval handle here so
+  // callers can discard partially-created maintenance safely.
   clearInterval(maintenance.tickInterval);
   clearInterval(maintenance.healthInterval);
   clearInterval(maintenance.dedupeCleanup);

src/gateway/server-runtime-startup-services.ts

@@ -1,3 +1,5 @@
+// Gateway startup-time runtime services.
+// Starts mode-dependent background monitors with inert handles for disabled paths.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ChannelHealthMonitor } from "./channel-health-monitor.js";
 import { startChannelHealthMonitor } from "./channel-health-monitor.js";

src/gateway/server-runtime-state.ts

@@ -1,3 +1,5 @@
+// Gateway HTTP/WebSocket runtime state factory.
+// Builds one server runtime with pinned plugin registries and lazy route handlers.
 import type { IncomingMessage, Server as HttpServer, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
 import { WebSocketServer } from "ws";

src/gateway/server-startup-early.ts

@@ -1,3 +1,5 @@
+// Gateway early-startup runtime helpers.
+// Starts discovery, remote skills, task maintenance, and delayed maintenance setup.
 import type { GatewayTailscaleMode } from "../config/types.gateway.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveCronJobsStorePath } from "../cron/store.js";

src/gateway/server-startup-post-attach.ts

@@ -1,3 +1,5 @@
+// Gateway post-attach startup sidecars.
+// Schedules warmups, sentinels, update checks, memory backend, and plugin services.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";