diff --git a/src/agents/codex-mcp-config.ts b/src/agents/codex-mcp-config.ts
index 377be3fea944..cad129c0682a 100644
--- a/src/agents/codex-mcp-config.ts
+++ b/src/agents/codex-mcp-config.ts
@@ -1,3 +1,8 @@
+/**
+ * Projects enabled bundle MCP servers into Codex app-server thread config.
+ * The projection keeps loopback approval defaults and header env placeholders
+ * compatible with Codex's MCP config shape.
+ */
 import crypto from "node:crypto";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import {
@@ -18,9 +23,6 @@ import type {
 } from "./codex-mcp-config.types.js";
 import { shouldCreateBundleMcpRuntimeForAttempt } from "./embedded-agent-runner/run/attempt-tool-construction-plan.js";
 
-// Projects enabled bundle MCP servers into Codex app-server thread config.
-// The projection keeps loopback approval defaults and header env placeholders
-// compatible with Codex's MCP config shape.
 export type {
   CodexBundleMcpThreadConfig,
   CodexMcpServersConfig,
@@ -64,6 +66,7 @@ function resolveCodexDefaultToolsApprovalMode(
   );
 }
 
+/** Normalizes one bundle MCP server into Codex's mcp_servers shape. */
 export function normalizeCodexMcpServerConfig(
   name: string,
   server: BundleMcpServerConfig,
diff --git a/src/agents/command-poll-backoff.ts b/src/agents/command-poll-backoff.ts
index d26134892f0e..601d542eafac 100644
--- a/src/agents/command-poll-backoff.ts
+++ b/src/agents/command-poll-backoff.ts
@@ -1,6 +1,9 @@
+/**
+ * Exponential backoff helpers for command-output polling. Session diagnostics
+ * use this state to slow no-output polls while resetting promptly on output.
+ */
 import type { SessionState } from "../logging/diagnostic-session-state.js";
 
-// Exponential backoff schedule for command polling
 const BACKOFF_SCHEDULE_MS = [5000, 10000, 30000, 60000];
 
 /**
diff --git a/src/agents/model-fallback-observation.ts b/src/agents/model-fallback-observation.ts
index 77ea0a1438b7..005533c272d1 100644
--- a/src/agents/model-fallback-observation.ts
+++ b/src/agents/model-fallback-observation.ts
@@ -1,11 +1,14 @@
+/**
+ * Structured logging for model fallback decisions. The log payload carries
+ * sanitized error observations plus step fields that make fallback chains
+ * auditable.
+ */
 import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { buildTextObservationFields } from "./embedded-agent-error-observation.js";
 import type { FailoverReason } from "./embedded-agent-helpers.js";
 import type { FallbackAttempt, ModelCandidate } from "./model-fallback.types.js";
 
-// Structured logging for model fallback decisions. The log payload carries
-// sanitized error observations plus step fields that make fallback chains auditable.
 const decisionLog = createSubsystemLogger("model-fallback").child("decision");
 
 /** Return whether fallback decision logging is enabled for warn-level events. */
@@ -36,6 +39,7 @@ function buildErrorObservationFields(error?: string): {
 
 type FallbackStepOutcome = "next_fallback" | "succeeded" | "chain_exhausted";
 
+/** Structured fields that describe one fallback-chain transition. */
 export type ModelFallbackStepFields = {
   fallbackStepType: "fallback_step";
   fallbackStepFromModel: string;
@@ -46,6 +50,7 @@ export type ModelFallbackStepFields = {
   fallbackStepFinalOutcome: FallbackStepOutcome;
 };
 
+/** Input payload for logging one model fallback decision. */
 export type ModelFallbackDecisionParams = {
   decision:
     | "skip_candidate"
diff --git a/src/agents/model-registry-loader.ts b/src/agents/model-registry-loader.ts
index b521c27cd6fc..ce049517aec0 100644
--- a/src/agents/model-registry-loader.ts
+++ b/src/agents/model-registry-loader.ts
@@ -1,11 +1,14 @@
+/**
+ * Shared model-registry loader for agent paths that need auth storage and
+ * plugin metadata resolved together before model discovery.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { discoverAuthStorage, discoverModels } from "./agent-model-discovery.js";
 import { resolveDefaultAgentDir } from "./agent-scope.js";
 import { resolveModelPluginMetadataSnapshot } from "./model-discovery-context.js";
 import type { ModelRegistry } from "./sessions/index.js";
 
-// Shared model-registry loader for agent paths that need auth storage and plugin
-// metadata resolved together before model discovery.
+/** Options controlling model discovery, credential reads, and normalization. */
 export type LoadAgentModelRegistryOptions = {
   providerFilter?: string;
   normalizeModels?: boolean;
diff --git a/src/agents/openai-completions-string-content.ts b/src/agents/openai-completions-string-content.ts
index c43f56d28286..d63595b7cdd0 100644
--- a/src/agents/openai-completions-string-content.ts
+++ b/src/agents/openai-completions-string-content.ts
@@ -1,5 +1,7 @@
-// OpenAI Chat Completions compatibility helpers. Some providers only accept
-// role/content messages with plain string content instead of text block arrays.
+/**
+ * OpenAI Chat Completions compatibility helpers. Some providers only accept
+ * role/content messages with plain string content instead of text block arrays.
+ */
 function flattenStringOnlyCompletionContent(content: unknown): unknown {
   if (!Array.isArray(content)) {
     return content;
diff --git a/src/agents/runtime-plugins.ts b/src/agents/runtime-plugins.ts
index 2dc2decced9f..961239ce6c4a 100644
--- a/src/agents/runtime-plugins.ts
+++ b/src/agents/runtime-plugins.ts
@@ -1,3 +1,7 @@
+/**
+ * Ensures runtime plugin registries are loaded for agent execution. Startup
+ * plugin IDs from metadata scope the load when available.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { normalizePluginsConfig } from "../plugins/config-state.js";
 import { getCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";
@@ -5,8 +9,6 @@ import { getActivePluginRuntimeSubagentMode } from "../plugins/runtime.js";
 import { ensureStandaloneRuntimePluginRegistryLoaded } from "../plugins/runtime/standalone-runtime-registry-loader.js";
 import { resolveUserPath } from "../utils.js";
 
-// Ensures runtime plugin registries are loaded for agent execution. Startup
-// plugin IDs from metadata scope the load when available.
 type StartupScopedPluginSnapshot = NonNullable<
   ReturnType<typeof getCurrentPluginMetadataSnapshot>
 > & {