@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/gateway/server.impl.js

@@ -1,54 +1,66 @@
+import path from "node:path";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
-import { initSubagentRegistry } from "../agents/subagent-registry.js";
+import { getActiveEmbeddedRunCount } from "../agents/pi-embedded-runner/runs.js";
 import { registerSkillsChangeListener } from "../agents/skills/refresh.js";
+import { initSubagentRegistry } from "../agents/subagent-registry.js";
+import { getTotalPendingReplies } from "../auto-reply/reply/dispatcher-registry.js";
 import { listChannelPlugins } from "../channels/plugins/index.js";
-import { createDefaultDeps } from "../cli/deps.js";
 import { formatCliCommand } from "../cli/command-format.js";
+import { createDefaultDeps } from "../cli/deps.js";
+import { isRestartEnabled } from "../config/commands.js";
 import { CONFIG_PATH, isNixMode, loadConfig, migrateLegacyConfig, readConfigFileSnapshot, writeConfigFile, } from "../config/config.js";
-import { isDiagnosticsEnabled } from "../infra/diagnostic-events.js";
-import { logAcceptedEnvOption } from "../infra/env.js";
 import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
 import { clearAgentRunContext, onAgentEvent } from "../infra/agent-events.js";
+import { ensureControlUiAssetsBuilt, resolveControlUiRootOverrideSync, resolveControlUiRootSync, } from "../infra/control-ui-assets.js";
+import { isDiagnosticsEnabled } from "../infra/diagnostic-events.js";
+import { logAcceptedEnvOption } from "../infra/env.js";
+import { createExecApprovalForwarder } from "../infra/exec-approval-forwarder.js";
 import { onHeartbeatEvent } from "../infra/heartbeat-events.js";
 import { startHeartbeatRunner } from "../infra/heartbeat-runner.js";
 import { getMachineDisplayName } from "../infra/machine-name.js";
 import { ensurePoolbotCliOnPath } from "../infra/path-env.js";
+import { setGatewaySigusr1RestartPolicy, setPreRestartDeferralCheck } from "../infra/restart.js";
 import { primeRemoteSkillsCache, refreshRemoteBinsForConnectedNodes, setSkillsRemoteRegistry, } from "../infra/skills-remote.js";
 import { scheduleGatewayUpdateCheck } from "../infra/update-startup.js";
-import { setGatewaySigusr1RestartPolicy } from "../infra/restart.js";
 import { startDiagnosticHeartbeat, stopDiagnosticHeartbeat } from "../logging/diagnostic.js";
 import { createSubsystemLogger, runtimeForLogger } from "../logging/subsystem.js";
+import { getGlobalHookRunner, runGlobalGatewayStopSafely } from "../plugins/hook-runner-global.js";
+import { createEmptyPluginRegistry } from "../plugins/registry.js";
+import { getTotalQueueSize } from "../process/command-queue.js";
 import { runOnboardingWizard } from "../wizard/onboarding.js";
+import { createAuthRateLimiter } from "./auth-rate-limit.js";
+import { startChannelHealthMonitor } from "./channel-health-monitor.js";
 import { startGatewayConfigReloader } from "./config-reload.js";
-import { getHealthCache, getHealthVersion, getPresenceVersion, incrementPresenceVersion, refreshGatewayHealthSnapshot, } from "./server/health-state.js";
-import { startGatewayDiscovery } from "./server-discovery-runtime.js";
+import { GATEWAY_EVENT_UPDATE_AVAILABLE, } from "./events.js";
 import { ExecApprovalManager } from "./exec-approval-manager.js";
-import { createExecApprovalHandlers } from "./server-methods/exec-approval.js";
-import { createExecApprovalForwarder } from "../infra/exec-approval-forwarder.js";
+import { NodeRegistry } from "./node-registry.js";
 import { createChannelManager } from "./server-channels.js";
 import { createAgentEventHandler } from "./server-chat.js";
 import { createGatewayCloseHandler } from "./server-close.js";
 import { buildGatewayCronService } from "./server-cron.js";
+import { startGatewayDiscovery } from "./server-discovery-runtime.js";
 import { applyGatewayLaneConcurrency } from "./server-lanes.js";
 import { startGatewayMaintenanceTimers } from "./server-maintenance.js";
-import { coreGatewayHandlers } from "./server-methods.js";
 import { GATEWAY_EVENTS, listGatewayMethods } from "./server-methods-list.js";
+import { coreGatewayHandlers } from "./server-methods.js";
+import { createExecApprovalHandlers } from "./server-methods/exec-approval.js";
+import { safeParseJson } from "./server-methods/nodes.helpers.js";
+import { hasConnectedMobileNode } from "./server-mobile-nodes.js";
 import { loadGatewayModelCatalog } from "./server-model-catalog.js";
-import { NodeRegistry } from "./node-registry.js";
 import { createNodeSubscriptionManager } from "./server-node-subscriptions.js";
-import { safeParseJson } from "./server-methods/nodes.helpers.js";
 import { loadGatewayPlugins } from "./server-plugins.js";
 import { createGatewayReloadHandlers } from "./server-reload-handlers.js";
 import { resolveGatewayRuntimeConfig } from "./server-runtime-config.js";
 import { createGatewayRuntimeState } from "./server-runtime-state.js";
-import { hasConnectedMobileNode } from "./server-mobile-nodes.js";
 import { resolveSessionKeyForRun } from "./server-session-key.js";
-import { startGatewaySidecars } from "./server-startup.js";
 import { logGatewayStartup } from "./server-startup-log.js";
+import { startGatewaySidecars } from "./server-startup.js";
 import { startGatewayTailscaleExposure } from "./server-tailscale.js";
-import { loadGatewayTlsRuntime } from "./server/tls.js";
 import { createWizardSessionTracker } from "./server-wizard-sessions.js";
 import { attachGatewayWsHandlers } from "./server-ws-runtime.js";
+import { getHealthCache, getHealthVersion, getPresenceVersion, incrementPresenceVersion, refreshGatewayHealthSnapshot, } from "./server/health-state.js";
+import { loadGatewayTlsRuntime } from "./server/tls.js";
+import { ensureGatewayStartupAuth } from "./startup-auth.js";
 export { __resetModelCatalogCacheForTest } from "./server-model-catalog.js";
 ensurePoolbotCliOnPath();
 const log = createSubsystemLogger("gateway");
@@ -63,8 +75,10 @@ const logReload = log.child("reload");
 const logHooks = log.child("hooks");
 const logPlugins = log.child("plugins");
 const logWsControl = log.child("ws");
+const gatewayRuntime = runtimeForLogger(log);
 const canvasRuntime = runtimeForLogger(logCanvas);
 export async function startGatewayServer(port = 18789, opts = {}) {
+    const minimalTestGateway = process.env.VITEST === "1" && process.env.POOLBOT_TEST_MINIMAL_GATEWAY === "1";
     // Ensure all default port derivations (browser/canvas) see the actual runtime port.
     process.env.POOLBOT_GATEWAY_PORT = String(port);
     process.env.CLAWDBOT_GATEWAY_PORT = String(port);
@@ -113,23 +127,43 @@ export async function startGatewayServer(port = 18789, opts = {}) {
             log.warn(`gateway: failed to persist plugin auto-enable changes: ${String(err)}`);
         }
     }
-    const cfgAtStart = loadConfig();
+    let cfgAtStart = loadConfig();
+    const authBootstrap = await ensureGatewayStartupAuth({
+        cfg: cfgAtStart,
+        env: process.env,
+        authOverride: opts.auth,
+        tailscaleOverride: opts.tailscale,
+        persist: true,
+    });
+    cfgAtStart = authBootstrap.cfg;
+    if (authBootstrap.generatedToken) {
+        if (authBootstrap.persistedGeneratedToken) {
+            log.info("Gateway auth token was missing. Generated a new token and saved it to config (gateway.auth.token).");
+        }
+        else {
+            log.warn("Gateway auth token was missing. Generated a runtime token for this startup without changing config; restart will generate a different token. Persist one with `poolbot config set gateway.auth.mode token` and `poolbot config set gateway.auth.token <token>`.");
+        }
+    }
     const diagnosticsEnabled = isDiagnosticsEnabled(cfgAtStart);
     if (diagnosticsEnabled) {
         startDiagnosticHeartbeat();
     }
-    setGatewaySigusr1RestartPolicy({ allowExternal: cfgAtStart.commands?.restart === true });
+    setGatewaySigusr1RestartPolicy({ allowExternal: isRestartEnabled(cfgAtStart) });
+    setPreRestartDeferralCheck(() => getTotalQueueSize() + getTotalPendingReplies() + getActiveEmbeddedRunCount());
     initSubagentRegistry();
     const defaultAgentId = resolveDefaultAgentId(cfgAtStart);
     const defaultWorkspaceDir = resolveAgentWorkspaceDir(cfgAtStart, defaultAgentId);
     const baseMethods = listGatewayMethods();
-    const { pluginRegistry, gatewayMethods: baseGatewayMethods } = loadGatewayPlugins({
-        cfg: cfgAtStart,
-        workspaceDir: defaultWorkspaceDir,
-        log,
-        coreGatewayHandlers,
-        baseMethods,
-    });
+    const emptyPluginRegistry = createEmptyPluginRegistry();
+    const { pluginRegistry, gatewayMethods: baseGatewayMethods } = minimalTestGateway
+        ? { pluginRegistry: emptyPluginRegistry, gatewayMethods: baseMethods }
+        : loadGatewayPlugins({
+            cfg: cfgAtStart,
+            workspaceDir: defaultWorkspaceDir,
+            log,
+            coreGatewayHandlers,
+            baseMethods,
+        });
     const channelLogs = Object.fromEntries(listChannelPlugins().map((plugin) => [plugin.id, logChannels.child(plugin.id)]));
     const channelRuntimeEnvs = Object.fromEntries(Object.entries(channelLogs).map(([id, logger]) => [id, runtimeForLogger(logger)]));
     const channelMethods = listChannelPlugins().flatMap((plugin) => plugin.gatewayMethods ?? []);
@@ -146,9 +180,46 @@ export async function startGatewayServer(port = 18789, opts = {}) {
         auth: opts.auth,
         tailscale: opts.tailscale,
     });
-    const { bindHost, controlUiEnabled, openAiChatCompletionsEnabled, openResponsesEnabled, openResponsesConfig, controlUiBasePath, resolvedAuth, tailscaleConfig, tailscaleMode, } = runtimeConfig;
+    const { bindHost, controlUiEnabled, openAiChatCompletionsEnabled, openResponsesEnabled, openResponsesConfig, controlUiBasePath, controlUiRoot: controlUiRootOverride, resolvedAuth, tailscaleConfig, tailscaleMode, } = runtimeConfig;
     let hooksConfig = runtimeConfig.hooksConfig;
     const canvasHostEnabled = runtimeConfig.canvasHostEnabled;
+    // Create auth rate limiter only when explicitly configured.
+    const rateLimitConfig = cfgAtStart.gateway?.auth?.rateLimit;
+    const authRateLimiter = rateLimitConfig
+        ? createAuthRateLimiter(rateLimitConfig)
+        : undefined;
+    let controlUiRootState;
+    if (controlUiRootOverride) {
+        const resolvedOverride = resolveControlUiRootOverrideSync(controlUiRootOverride);
+        const resolvedOverridePath = path.resolve(controlUiRootOverride);
+        controlUiRootState = resolvedOverride
+            ? { kind: "resolved", path: resolvedOverride }
+            : { kind: "invalid", path: resolvedOverridePath };
+        if (!resolvedOverride) {
+            log.warn(`gateway: controlUi.root not found at ${resolvedOverridePath}`);
+        }
+    }
+    else if (controlUiEnabled) {
+        let resolvedRoot = resolveControlUiRootSync({
+            moduleUrl: import.meta.url,
+            argv1: process.argv[1],
+            cwd: process.cwd(),
+        });
+        if (!resolvedRoot) {
+            const ensureResult = await ensureControlUiAssetsBuilt(gatewayRuntime);
+            if (!ensureResult.ok && ensureResult.message) {
+                log.warn(`gateway: ${ensureResult.message}`);
+            }
+            resolvedRoot = resolveControlUiRootSync({
+                moduleUrl: import.meta.url,
+                argv1: process.argv[1],
+                cwd: process.cwd(),
+            });
+        }
+        controlUiRootState = resolvedRoot
+            ? { kind: "resolved", path: resolvedRoot }
+            : { kind: "missing" };
+    }
     const wizardRunner = opts.wizardRunner ?? runOnboardingWizard;
     const { wizardSessions, findRunningWizard, purgeWizardSession } = createWizardSessionTracker();
     const deps = createDefaultDeps();
@@ -157,16 +228,18 @@ export async function startGatewayServer(port = 18789, opts = {}) {
     if (cfgAtStart.gateway?.tls?.enabled && !gatewayTls.enabled) {
         throw new Error(gatewayTls.error ?? "gateway tls: failed to enable");
     }
-    const { canvasHost, httpServer, httpServers, httpBindHosts, wss, clients, broadcast, agentRunSeq, dedupe, chatRunState, chatRunBuffers, chatDeltaSentAt, addChatRun, removeChatRun, chatAbortControllers, broadcastToConnIds, toolEventRecipients, } = await createGatewayRuntimeState({
+    const { canvasHost, httpServer, httpServers, httpBindHosts, wss, clients, broadcast, broadcastToConnIds, agentRunSeq, dedupe, chatRunState, chatRunBuffers, chatDeltaSentAt, addChatRun, removeChatRun, chatAbortControllers, toolEventRecipients, } = await createGatewayRuntimeState({
         cfg: cfgAtStart,
         bindHost,
         port,
         controlUiEnabled,
         controlUiBasePath,
+        controlUiRoot: controlUiRootState,
         openAiChatCompletionsEnabled,
         openResponsesEnabled,
         openResponsesConfig,
         resolvedAuth,
+        rateLimiter: authRateLimiter,
         gatewayTls,
         hooksConfig: () => hooksConfig,
         pluginRegistry,
@@ -209,68 +282,115 @@ export async function startGatewayServer(port = 18789, opts = {}) {
         channelRuntimeEnvs,
     });
     const { getRuntimeSnapshot, startChannels, startChannel, stopChannel, markChannelLoggedOut } = channelManager;
-    const machineDisplayName = await getMachineDisplayName();
-    const discovery = await startGatewayDiscovery({
-        machineDisplayName,
-        port,
-        gatewayTls: gatewayTls.enabled
-            ? { enabled: true, fingerprintSha256: gatewayTls.fingerprintSha256 }
-            : undefined,
-        wideAreaDiscoveryEnabled: cfgAtStart.discovery?.wideArea?.enabled === true,
-        tailscaleMode,
-        mdnsMode: cfgAtStart.discovery?.mdns?.mode,
-        logDiscovery,
-    });
-    bonjourStop = discovery.bonjourStop;
-    setSkillsRemoteRegistry(nodeRegistry);
-    void primeRemoteSkillsCache();
+    if (!minimalTestGateway) {
+        const machineDisplayName = await getMachineDisplayName();
+        const discovery = await startGatewayDiscovery({
+            machineDisplayName,
+            port,
+            gatewayTls: gatewayTls.enabled
+                ? { enabled: true, fingerprintSha256: gatewayTls.fingerprintSha256 }
+                : undefined,
+            wideAreaDiscoveryEnabled: cfgAtStart.discovery?.wideArea?.enabled === true,
+            wideAreaDiscoveryDomain: cfgAtStart.discovery?.wideArea?.domain,
+            tailscaleMode,
+            mdnsMode: cfgAtStart.discovery?.mdns?.mode,
+            logDiscovery,
+        });
+        bonjourStop = discovery.bonjourStop;
+    }
+    if (!minimalTestGateway) {
+        setSkillsRemoteRegistry(nodeRegistry);
+        void primeRemoteSkillsCache();
+    }
     // Debounce skills-triggered node probes to avoid feedback loops and rapid-fire invokes.
     // Skills changes can happen in bursts (e.g., file watcher events), and each probe
     // takes time to complete. A 30-second delay ensures we batch changes together.
     let skillsRefreshTimer = null;
     const skillsRefreshDelayMs = 30_000;
-    const skillsChangeUnsub = registerSkillsChangeListener((event) => {
-        if (event.reason === "remote-node")
-            return;
-        if (skillsRefreshTimer)
-            clearTimeout(skillsRefreshTimer);
-        skillsRefreshTimer = setTimeout(() => {
-            skillsRefreshTimer = null;
-            const latest = loadConfig();
-            void refreshRemoteBinsForConnectedNodes(latest);
-        }, skillsRefreshDelayMs);
-    });
-    const { tickInterval, healthInterval, dedupeCleanup } = startGatewayMaintenanceTimers({
-        broadcast,
-        nodeSendToAllSubscribed,
-        getPresenceVersion,
-        getHealthVersion,
-        refreshGatewayHealthSnapshot,
-        logHealth,
-        dedupe,
-        chatAbortControllers,
-        chatRunState,
-        chatRunBuffers,
-        chatDeltaSentAt,
-        removeChatRun,
-        agentRunSeq,
-        nodeSendToSession,
-    });
-    const agentUnsub = onAgentEvent(createAgentEventHandler({
-        broadcast,
-        broadcastToConnIds,
-        nodeSendToSession,
-        agentRunSeq,
-        chatRunState,
-        resolveSessionKeyForRun,
-        clearAgentRunContext,
-        toolEventRecipients,
-    }));
-    const heartbeatUnsub = onHeartbeatEvent((evt) => {
-        broadcast("heartbeat", evt, { dropIfSlow: true });
-    });
-    let heartbeatRunner = startHeartbeatRunner({ cfg: cfgAtStart });
-    void cron.start().catch((err) => logCron.error(`failed to start: ${String(err)}`));
+    const skillsChangeUnsub = minimalTestGateway
+        ? () => { }
+        : registerSkillsChangeListener((event) => {
+            if (event.reason === "remote-node") {
+                return;
+            }
+            if (skillsRefreshTimer) {
+                clearTimeout(skillsRefreshTimer);
+            }
+            skillsRefreshTimer = setTimeout(() => {
+                skillsRefreshTimer = null;
+                const latest = loadConfig();
+                void refreshRemoteBinsForConnectedNodes(latest);
+            }, skillsRefreshDelayMs);
+        });
+    const noopInterval = () => setInterval(() => { }, 1 << 30);
+    let tickInterval = noopInterval();
+    let healthInterval = noopInterval();
+    let dedupeCleanup = noopInterval();
+    if (!minimalTestGateway) {
+        ({ tickInterval, healthInterval, dedupeCleanup } = startGatewayMaintenanceTimers({
+            broadcast,
+            nodeSendToAllSubscribed,
+            getPresenceVersion,
+            getHealthVersion,
+            refreshGatewayHealthSnapshot,
+            logHealth,
+            dedupe,
+            chatAbortControllers,
+            chatRunState,
+            chatRunBuffers,
+            chatDeltaSentAt,
+            removeChatRun,
+            agentRunSeq,
+            nodeSendToSession,
+        }));
+    }
+    const agentUnsub = minimalTestGateway
+        ? null
+        : onAgentEvent(createAgentEventHandler({
+            broadcast,
+            broadcastToConnIds,
+            nodeSendToSession,
+            agentRunSeq,
+            chatRunState,
+            resolveSessionKeyForRun,
+            clearAgentRunContext,
+            toolEventRecipients,
+        }));
+    const heartbeatUnsub = minimalTestGateway
+        ? null
+        : onHeartbeatEvent((evt) => {
+            broadcast("heartbeat", evt, { dropIfSlow: true });
+        });
+    let heartbeatRunner = minimalTestGateway
+        ? {
+            stop: () => { },
+            updateConfig: () => { },
+        }
+        : startHeartbeatRunner({ cfg: cfgAtStart });
+    const healthCheckMinutes = cfgAtStart.gateway?.channelHealthCheckMinutes;
+    const healthCheckDisabled = healthCheckMinutes === 0;
+    const channelHealthMonitor = healthCheckDisabled
+        ? null
+        : startChannelHealthMonitor({
+            channelManager,
+            checkIntervalMs: (healthCheckMinutes ?? 5) * 60_000,
+        });
+    if (!minimalTestGateway) {
+        void cron.start().catch((err) => logCron.error(`failed to start: ${String(err)}`));
+    }
+    // Recover pending outbound deliveries from previous crash/restart.
+    if (!minimalTestGateway) {
+        void (async () => {
+            const { recoverPendingDeliveries } = await import("../infra/outbound/delivery-queue.js");
+            const { deliverOutboundPayloads } = await import("../infra/outbound/deliver.js");
+            const logRecovery = log.child("delivery-recovery");
+            await recoverPendingDeliveries({
+                deliver: deliverOutboundPayloads,
+                log: logRecovery,
+                cfg: cfgAtStart,
+            });
+        })().catch((err) => log.error(`Delivery recovery failed: ${String(err)}`));
+    }
     const execApprovalManager = new ExecApprovalManager();
     const execApprovalForwarder = createExecApprovalForwarder();
     const execApprovalHandlers = createExecApprovalHandlers(execApprovalManager, {
@@ -285,6 +405,7 @@ export async function startGatewayServer(port = 18789, opts = {}) {
         canvasHostEnabled: Boolean(canvasHost),
         canvasHostServerPort,
         resolvedAuth,
+        rateLimiter: authRateLimiter,
         gatewayMethods,
         events: GATEWAY_EVENTS,
         logGateway: log,
@@ -299,6 +420,7 @@ export async function startGatewayServer(port = 18789, opts = {}) {
             deps,
             cron,
             cronStorePath,
+            execApprovalManager,
             loadGatewayModelCatalog,
             getHealthCache,
             refreshHealthSnapshot: refreshGatewayHealthSnapshot,
@@ -344,63 +466,90 @@ export async function startGatewayServer(port = 18789, opts = {}) {
         log,
         isNixMode,
     });
-    scheduleGatewayUpdateCheck({ cfg: cfgAtStart, log, isNixMode });
-    const tailscaleCleanup = await startGatewayTailscaleExposure({
-        tailscaleMode,
-        resetOnExit: tailscaleConfig.resetOnExit,
-        port,
-        controlUiBasePath,
-        logTailscale,
-    });
+    if (!minimalTestGateway) {
+        scheduleGatewayUpdateCheck({
+            cfg: cfgAtStart,
+            log,
+            isNixMode,
+            onUpdateAvailableChange: (updateAvailable) => {
+                const payload = { updateAvailable };
+                broadcast(GATEWAY_EVENT_UPDATE_AVAILABLE, payload, { dropIfSlow: true });
+            },
+        });
+    }
+    const tailscaleCleanup = minimalTestGateway
+        ? null
+        : await startGatewayTailscaleExposure({
+            tailscaleMode,
+            resetOnExit: tailscaleConfig.resetOnExit,
+            port,
+            controlUiBasePath,
+            logTailscale,
+        });
     let browserControl = null;
-    ({ browserControl, pluginServices } = await startGatewaySidecars({
-        cfg: cfgAtStart,
-        pluginRegistry,
-        defaultWorkspaceDir,
-        deps,
-        startChannels,
-        log,
-        logHooks,
-        logChannels,
-        logBrowser,
-    }));
-    const { applyHotReload, requestGatewayRestart } = createGatewayReloadHandlers({
-        deps,
-        broadcast,
-        getState: () => ({
-            hooksConfig,
-            heartbeatRunner,
-            cronState,
-            browserControl,
-        }),
-        setState: (nextState) => {
-            hooksConfig = nextState.hooksConfig;
-            heartbeatRunner = nextState.heartbeatRunner;
-            cronState = nextState.cronState;
-            cron = cronState.cron;
-            cronStorePath = cronState.storePath;
-            browserControl = nextState.browserControl;
-        },
-        startChannel,
-        stopChannel,
-        logHooks,
-        logBrowser,
-        logChannels,
-        logCron,
-        logReload,
-    });
-    const configReloader = startGatewayConfigReloader({
-        initialConfig: cfgAtStart,
-        readSnapshot: readConfigFileSnapshot,
-        onHotReload: applyHotReload,
-        onRestart: requestGatewayRestart,
-        log: {
-            info: (msg) => logReload.info(msg),
-            warn: (msg) => logReload.warn(msg),
-            error: (msg) => logReload.error(msg),
-        },
-        watchPath: CONFIG_PATH,
-    });
+    if (!minimalTestGateway) {
+        ({ browserControl, pluginServices } = await startGatewaySidecars({
+            cfg: cfgAtStart,
+            pluginRegistry,
+            defaultWorkspaceDir,
+            deps,
+            startChannels,
+            log,
+            logHooks,
+            logChannels,
+            logBrowser,
+        }));
+    }
+    // Run gateway_start plugin hook (fire-and-forget)
+    if (!minimalTestGateway) {
+        const hookRunner = getGlobalHookRunner();
+        if (hookRunner?.hasHooks("gateway_start")) {
+            void hookRunner.runGatewayStart({ port }, { port }).catch((err) => {
+                log.warn(`gateway_start hook failed: ${String(err)}`);
+            });
+        }
+    }
+    const configReloader = minimalTestGateway
+        ? { stop: async () => { } }
+        : (() => {
+            const { applyHotReload, requestGatewayRestart } = createGatewayReloadHandlers({
+                deps,
+                broadcast,
+                getState: () => ({
+                    hooksConfig,
+                    heartbeatRunner,
+                    cronState,
+                    browserControl,
+                }),
+                setState: (nextState) => {
+                    hooksConfig = nextState.hooksConfig;
+                    heartbeatRunner = nextState.heartbeatRunner;
+                    cronState = nextState.cronState;
+                    cron = cronState.cron;
+                    cronStorePath = cronState.storePath;
+                    browserControl = nextState.browserControl;
+                },
+                startChannel,
+                stopChannel,
+                logHooks,
+                logBrowser,
+                logChannels,
+                logCron,
+                logReload,
+            });
+            return startGatewayConfigReloader({
+                initialConfig: cfgAtStart,
+                readSnapshot: readConfigFileSnapshot,
+                onHotReload: applyHotReload,
+                onRestart: requestGatewayRestart,
+                log: {
+                    info: (msg) => logReload.info(msg),
+                    warn: (msg) => logReload.warn(msg),
+                    error: (msg) => logReload.error(msg),
+                },
+                watchPath: CONFIG_PATH,
+            });
+        })();
     const close = createGatewayCloseHandler({
         bonjourStop,
         tailscaleCleanup,
@@ -427,6 +576,12 @@ export async function startGatewayServer(port = 18789, opts = {}) {
     });
     return {
         close: async (opts) => {
+            // Run gateway_stop plugin hook before shutdown
+            await runGlobalGatewayStopSafely({
+                event: { reason: opts?.reason ?? "gateway stopping" },
+                ctx: { port },
+                onError: (err) => log.warn(`gateway_stop hook failed: ${String(err)}`),
+            });
             if (diagnosticsEnabled) {
                 stopDiagnosticHeartbeat();
             }
@@ -435,6 +590,8 @@ export async function startGatewayServer(port = 18789, opts = {}) {
                 skillsRefreshTimer = null;
             }
             skillsChangeUnsub();
+            authRateLimiter?.dispose();
+            channelHealthMonitor?.stop();
             await close(opts);
         },
     };

package/dist/gateway/session-preview.test-helpers.js

@@ -0,0 +1,11 @@
+export function createToolSummaryPreviewTranscriptLines(sessionId) {
+    return [
+        JSON.stringify({ type: "session", version: 1, id: sessionId }),
+        JSON.stringify({ message: { role: "user", content: "Hello" } }),
+        JSON.stringify({ message: { role: "assistant", content: "Hi" } }),
+        JSON.stringify({
+            message: { role: "assistant", content: [{ type: "toolcall", name: "weather" }] },
+        }),
+        JSON.stringify({ message: { role: "assistant", content: "Forecast ready" } }),
+    ];
+}