diff --git a/src/agents/cli-runner/bundle-mcp-adapter-shared.ts b/src/agents/cli-runner/bundle-mcp-adapter-shared.ts
index 2387add77ffa..2bf81904cec5 100644
--- a/src/agents/cli-runner/bundle-mcp-adapter-shared.ts
+++ b/src/agents/cli-runner/bundle-mcp-adapter-shared.ts
@@ -1,8 +1,11 @@
+/**
+ * Shared normalization helpers for CLI-specific bundle MCP adapters.
+ */
 import { isRecord } from "../../../packages/normalization-core/src/record-coerce.js";
 import type { BundleMcpServerConfig } from "../../plugins/bundle-mcp.js";
+/** Re-exported record guard for adapter modules that share loose JSON inputs. */
 export { isRecord } from "../../../packages/normalization-core/src/record-coerce.js";
 
-// Shared normalization helpers for CLI-specific bundle MCP adapters.
 function normalizeStringArray(value: unknown): string[] | undefined {
   return Array.isArray(value) && value.every((entry) => typeof entry === "string")
     ? [...value]
diff --git a/src/agents/cli-runner/bundle-mcp-claude.ts b/src/agents/cli-runner/bundle-mcp-claude.ts
index 61d07bae4e64..0d79cca19f6f 100644
--- a/src/agents/cli-runner/bundle-mcp-claude.ts
+++ b/src/agents/cli-runner/bundle-mcp-claude.ts
@@ -1,7 +1,8 @@
+/**
+ * Claude CLI argument helpers for OpenClaw-managed bundle MCP config.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
-// Claude CLI MCP argument helpers. OpenClaw owns the generated config path, so
-// existing mcp-config flags are stripped before injecting strict config args.
 /** Find an existing Claude `--mcp-config` argument value. */
 export function findClaudeMcpConfigPath(args?: string[]): string | undefined {
   if (!args?.length) {
diff --git a/src/agents/cli-runner/bundle-mcp-codex.ts b/src/agents/cli-runner/bundle-mcp-codex.ts
index bc67fee968fd..9a1407faa07c 100644
--- a/src/agents/cli-runner/bundle-mcp-codex.ts
+++ b/src/agents/cli-runner/bundle-mcp-codex.ts
@@ -1,3 +1,6 @@
+/**
+ * Codex CLI and app-server bundle MCP projection helpers.
+ */
 import { normalizeConfiguredMcpServers } from "../../config/mcp-config-normalize.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { BundleMcpConfig, BundleMcpServerConfig } from "../../plugins/bundle-mcp.js";
@@ -54,6 +57,7 @@ function isCodexMcpServerAllowedForAgent(
   return agentIds.includes(normalizeAgentId(options.agentId));
 }
 
+/** Returns Codex CLI args with TOML MCP server overrides injected. */
 export function injectCodexMcpConfigArgs(
   args: string[] | undefined,
   config: BundleMcpConfig,
diff --git a/src/agents/cli-runner/bundle-mcp-gemini.ts b/src/agents/cli-runner/bundle-mcp-gemini.ts
index 5dea8fb8b271..f1841d0d0a06 100644
--- a/src/agents/cli-runner/bundle-mcp-gemini.ts
+++ b/src/agents/cli-runner/bundle-mcp-gemini.ts
@@ -1,3 +1,6 @@
+/**
+ * Gemini CLI bundle MCP adapter that writes temporary system settings files.
+ */
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -11,8 +14,6 @@ import {
   normalizeStringRecord,
 } from "./bundle-mcp-adapter-shared.js";
 
-// Gemini CLI MCP adapter. It writes a temporary system settings file that merges
-// any existing settings with enabled bundle MCP servers.
 async function readJsonObject(filePath: string): Promise<Record<string, unknown>> {
   const raw = await tryReadJson<unknown>(filePath);
   return raw && typeof raw === "object" && !Array.isArray(raw)
@@ -58,6 +59,7 @@ function normalizeGeminiServerConfig(
   return next;
 }
 
+/** Writes merged Gemini system settings and returns env plus cleanup hook. */
 export async function writeGeminiSystemSettings(
   mergedConfig: BundleMcpConfig,
   inheritedEnv: Record<string, string> | undefined,
diff --git a/src/agents/cli-runner/bundle-mcp.ts b/src/agents/cli-runner/bundle-mcp.ts
index 9ed9ed7d46fd..bb7d6e89575f 100644
--- a/src/agents/cli-runner/bundle-mcp.ts
+++ b/src/agents/cli-runner/bundle-mcp.ts
@@ -1,3 +1,6 @@
+/**
+ * Prepares bundled MCP configuration for CLI runner backends.
+ */
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -14,8 +17,6 @@ import { findClaudeMcpConfigPath, injectClaudeMcpConfigArgs } from "./bundle-mcp
 import { injectCodexMcpConfigArgs } from "./bundle-mcp-codex.js";
 import { writeGeminiSystemSettings } from "./bundle-mcp-gemini.js";
 
-// Prepares bundle MCP configuration for CLI backends. Each backend receives MCP
-// config in its native form while OpenClaw records stable hashes for resume checks.
 type PreparedCliBundleMcpConfig = {
   backend: CliBackendConfig;
   cleanup?: () => Promise<void>;