diff --git a/src/agents/embedded-agent-runner/run/auth-controller.ts b/src/agents/embedded-agent-runner/run/auth-controller.ts
index 77558162468d..40b868ea22b4 100644
--- a/src/agents/embedded-agent-runner/run/auth-controller.ts
+++ b/src/agents/embedded-agent-runner/run/auth-controller.ts
@@ -1,3 +1,6 @@
+/**
+ * Coordinates provider auth, profile rotation, and runtime auth refresh.
+ */
 import type { ThinkLevel } from "../../../auto-reply/thinking.js";
 import { formatErrorMessage } from "../../../infra/errors.js";
 import type { Model } from "../../../llm/types.js";
diff --git a/src/agents/embedded-agent-runner/run/auth-profile-failure-policy.ts b/src/agents/embedded-agent-runner/run/auth-profile-failure-policy.ts
index fd29e72c1826..6b9b9f1f33c4 100644
--- a/src/agents/embedded-agent-runner/run/auth-profile-failure-policy.ts
+++ b/src/agents/embedded-agent-runner/run/auth-profile-failure-policy.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves why an auth profile failed during provider auth selection.
+ */
 import type { AuthProfileFailureReason } from "../../auth-profiles/types.js";
 import type { FailoverReason } from "../../embedded-agent-helpers/types.js";
 import type { AuthProfileFailurePolicy } from "./auth-profile-failure-policy.types.js";
diff --git a/src/agents/embedded-agent-runner/run/backend.ts b/src/agents/embedded-agent-runner/run/backend.ts
index 47c80bb12d49..0082c5ccc69d 100644
--- a/src/agents/embedded-agent-runner/run/backend.ts
+++ b/src/agents/embedded-agent-runner/run/backend.ts
@@ -1,3 +1,6 @@
+/**
+ * Dispatches embedded attempts to native harness or OpenClaw backend execution.
+ */
 import { runAgentHarnessAttempt } from "../../harness/selection.js";
 import type { EmbeddedRunAttemptParams, EmbeddedRunAttemptResult } from "./types.js";
 
diff --git a/src/agents/embedded-agent-runner/run/codex-app-server-recovery.ts b/src/agents/embedded-agent-runner/run/codex-app-server-recovery.ts
index 2965c64ff51d..c40d60543095 100644
--- a/src/agents/embedded-agent-runner/run/codex-app-server-recovery.ts
+++ b/src/agents/embedded-agent-runner/run/codex-app-server-recovery.ts
@@ -1,3 +1,6 @@
+/**
+ * Detects Codex app-server failures that should retry with recovery.
+ */
 import type { EmbeddedRunAttemptResult } from "./types.js";
 
 /**
diff --git a/src/agents/embedded-agent-runner/run/compaction-retry-aggregate-timeout.ts b/src/agents/embedded-agent-runner/run/compaction-retry-aggregate-timeout.ts
index 435e5083d5e2..38d9fd956deb 100644
--- a/src/agents/embedded-agent-runner/run/compaction-retry-aggregate-timeout.ts
+++ b/src/agents/embedded-agent-runner/run/compaction-retry-aggregate-timeout.ts
@@ -1,3 +1,6 @@
+/**
+ * Caps compaction retry waits against the aggregate run timeout.
+ */
 import { resolveTimerTimeoutMs } from "@openclaw/normalization-core/number-coercion";
 
 /**
diff --git a/src/agents/embedded-agent-runner/run/compaction-timeout.ts b/src/agents/embedded-agent-runner/run/compaction-timeout.ts
index 2f660951178b..e5cbb04b12e8 100644
--- a/src/agents/embedded-agent-runner/run/compaction-timeout.ts
+++ b/src/agents/embedded-agent-runner/run/compaction-timeout.ts
@@ -1,3 +1,6 @@
+/**
+ * Computes run timeout behavior while compaction is in progress.
+ */
 import type { AgentMessage } from "../../runtime/index.js";
 
 /** Timeout state used to distinguish normal run deadlines from compaction stalls. */
diff --git a/src/agents/embedded-agent-runner/run/failover-observation.ts b/src/agents/embedded-agent-runner/run/failover-observation.ts
index b319093c1dfb..ea912f6ce1e8 100644
--- a/src/agents/embedded-agent-runner/run/failover-observation.ts
+++ b/src/agents/embedded-agent-runner/run/failover-observation.ts
@@ -1,3 +1,6 @@
+/**
+ * Logs redacted failover decisions for embedded-agent attempts.
+ */
 import { redactIdentifier } from "../../../logging/redact-identifier.js";
 import type { AuthProfileFailureReason } from "../../auth-profiles.js";
 import {
diff --git a/src/agents/embedded-agent-runner/run/failover-policy.ts b/src/agents/embedded-agent-runner/run/failover-policy.ts
index 69d05a55c437..da04ffc31447 100644
--- a/src/agents/embedded-agent-runner/run/failover-policy.ts
+++ b/src/agents/embedded-agent-runner/run/failover-policy.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves retry, fallback, and terminal failover decisions for a run.
+ */
 import type { FailoverReason } from "../../embedded-agent-helpers.js";
 
 /** Failover action selected for one embedded run failure decision point. */
diff --git a/src/agents/embedded-agent-runner/run/fallbacks.ts b/src/agents/embedded-agent-runner/run/fallbacks.ts
index a1b53a050659..2623634b7d2f 100644
--- a/src/agents/embedded-agent-runner/run/fallbacks.ts
+++ b/src/agents/embedded-agent-runner/run/fallbacks.ts
@@ -1,3 +1,6 @@
+/**
+ * Reads configured embedded-run model fallback availability.
+ */
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { hasConfiguredModelFallbacks } from "../../agent-scope.js";
 
diff --git a/src/agents/embedded-agent-runner/run/helpers.ts b/src/agents/embedded-agent-runner/run/helpers.ts
index 8a309aaed3dd..31fc1f6486d4 100644
--- a/src/agents/embedded-agent-runner/run/helpers.ts
+++ b/src/agents/embedded-agent-runner/run/helpers.ts
@@ -1,3 +1,6 @@
+/**
+ * Shared run helpers for retry limits, model reporting, and final text.
+ */
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { generateSecureToken } from "../../../infra/secure-random.js";
 import type { AssistantMessage } from "../../../llm/types.js";
diff --git a/src/agents/embedded-agent-runner/run/history-image-prune.ts b/src/agents/embedded-agent-runner/run/history-image-prune.ts
index f5d3777542a1..5c6a223f6753 100644
--- a/src/agents/embedded-agent-runner/run/history-image-prune.ts
+++ b/src/agents/embedded-agent-runner/run/history-image-prune.ts
@@ -1,3 +1,6 @@
+/**
+ * Prunes already-processed image payloads from replayed prompt history.
+ */
 import type { AgentMessage } from "../../runtime/index.js";
 
 /** Replacement text for old image blocks that were already available to the model. */
diff --git a/src/agents/embedded-agent-runner/run/images.ts b/src/agents/embedded-agent-runner/run/images.ts
index 2cd3a51574f5..bece363407fe 100644
--- a/src/agents/embedded-agent-runner/run/images.ts
+++ b/src/agents/embedded-agent-runner/run/images.ts
@@ -1,3 +1,6 @@
+/**
+ * Detects, resolves, and loads prompt image references for model input.
+ */
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { formatErrorMessage } from "../../../infra/errors.js";
diff --git a/src/agents/embedded-agent-runner/run/incomplete-turn.ts b/src/agents/embedded-agent-runner/run/incomplete-turn.ts
index e5edccb675a3..fab5f21e356b 100644
--- a/src/agents/embedded-agent-runner/run/incomplete-turn.ts
+++ b/src/agents/embedded-agent-runner/run/incomplete-turn.ts
@@ -1,3 +1,6 @@
+/**
+ * Classifies incomplete terminal assistant turns and retry instructions.
+ */
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
diff --git a/src/agents/embedded-agent-runner/run/llm-idle-timeout.ts b/src/agents/embedded-agent-runner/run/llm-idle-timeout.ts
index ab6fa8a3776b..e5320ee0cde8 100644
--- a/src/agents/embedded-agent-runner/run/llm-idle-timeout.ts
+++ b/src/agents/embedded-agent-runner/run/llm-idle-timeout.ts
@@ -1,3 +1,6 @@
+/**
+ * Wraps LLM streams with idle-timeout detection and diagnostics.
+ */
 import {
   finiteSecondsToTimerSafeMilliseconds,
   clampTimerTimeoutMs,