diff --git a/src/auto-reply/reply/agent-runner-usage-line.ts b/src/auto-reply/reply/agent-runner-usage-line.ts
index 1acfc8dd5a20..ce9b97638e41 100644
--- a/src/auto-reply/reply/agent-runner-usage-line.ts
+++ b/src/auto-reply/reply/agent-runner-usage-line.ts
@@ -1,3 +1,4 @@
+/** Formats and appends token/cost usage lines to reply payloads. */
 import {
   estimateUsageCost,
   formatTokenCount,
diff --git a/src/auto-reply/reply/channel-context.ts b/src/auto-reply/reply/channel-context.ts
index 133264e2d6ab..94c056187234 100644
--- a/src/auto-reply/reply/channel-context.ts
+++ b/src/auto-reply/reply/channel-context.ts
@@ -1,3 +1,4 @@
+/** Resolves channel and account context for command handlers. */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -30,6 +31,7 @@ type ChannelAccountParams = {
   };
 };
 
+/** Resolves the command surface channel from inbound context and command state. */
 export function resolveCommandSurfaceChannel(params: CommandSurfaceParams): string {
   const channel =
     params.ctx.OriginatingChannel ??
@@ -39,6 +41,7 @@ export function resolveCommandSurfaceChannel(params: CommandSurfaceParams): stri
   return normalizeOptionalLowercaseString(channel) ?? "";
 }
 
+/** Resolves command account id, falling back to plugin default account config. */
 export function resolveChannelAccountId(params: ChannelAccountParams): string {
   const accountId = normalizeOptionalString(params.ctx.AccountId) ?? "";
   if (accountId) {
diff --git a/src/auto-reply/reply/commands-diagnostics.ts b/src/auto-reply/reply/commands-diagnostics.ts
index 78c38263f836..5b32fad18541 100644
--- a/src/auto-reply/reply/commands-diagnostics.ts
+++ b/src/auto-reply/reply/commands-diagnostics.ts
@@ -1,3 +1,4 @@
+/** Handles diagnostics commands and private owner routing for sensitive diagnostics output. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveSessionAgentId } from "../../agents/agent-scope.js";
 import { createExecTool } from "../../agents/bash-tools.js";
@@ -58,6 +59,7 @@ const defaultDiagnosticsCommandDeps: DiagnosticsCommandDeps = {
   deliverPrivateDiagnosticsReply,
 };
 
+/** Creates a diagnostics command handler with injectable private-route dependencies. */
 export function createDiagnosticsCommandHandler(
   deps: Partial<DiagnosticsCommandDeps> = {},
 ): CommandHandler {
@@ -69,6 +71,7 @@ export function createDiagnosticsCommandHandler(
     await handleDiagnosticsCommandWithDeps(resolvedDeps, params, allowTextCommands);
 }
 
+/** Default diagnostics command handler. */
 export const handleDiagnosticsCommand: CommandHandler = createDiagnosticsCommandHandler();
 
 async function handleDiagnosticsCommandWithDeps(
diff --git a/src/auto-reply/reply/commands-private-route.ts b/src/auto-reply/reply/commands-private-route.ts
index f8ef2fc7bbef..793d9482b64a 100644
--- a/src/auto-reply/reply/commands-private-route.ts
+++ b/src/auto-reply/reply/commands-private-route.ts
@@ -1,3 +1,4 @@
+/** Private command reply routing for sensitive owner-only command output. */
 import { resolveExpiresAtMsFromDurationMs } from "@openclaw/normalization-core/number-coercion";
 import {
   normalizeLowercaseStringOrEmpty,
@@ -14,6 +15,7 @@ import type { ReplyPayload } from "../types.js";
 import type { HandleCommandsParams } from "./commands-types.js";
 import { routeReply } from "./route-reply.js";
 
+/** Resolved private delivery target for command replies and approvals. */
 export type PrivateCommandRouteTarget = {
   channel: string;
   to: string;
@@ -24,6 +26,7 @@ export type PrivateCommandRouteTarget = {
 const PRIVATE_COMMAND_APPROVAL_ROUTE_TTL_MS = 5 * 60_000;
 const EXPIRED_PRIVATE_COMMAND_APPROVAL_ROUTE_EXPIRES_AT_MS = 0;
 
+/** Resolves expiry timestamp for temporary private approval routes. */
 export function resolvePrivateCommandApprovalRouteExpiresAtMs(nowMs = Date.now()): number {
   return (
     resolveExpiresAtMsFromDurationMs(PRIVATE_COMMAND_APPROVAL_ROUTE_TTL_MS, { nowMs }) ??
@@ -31,6 +34,7 @@ export function resolvePrivateCommandApprovalRouteExpiresAtMs(nowMs = Date.now()
   );
 }
 
+/** Finds private owner DM routes that can receive sensitive command replies. */
 export async function resolvePrivateCommandRouteTargets(params: {
   commandParams: HandleCommandsParams;
   request: ExecApprovalRequest;
@@ -80,6 +84,7 @@ export async function resolvePrivateCommandRouteTargets(params: {
   });
 }
 
+/** Delivers a sensitive command reply to the resolved private targets. */
 export async function deliverPrivateCommandReply(params: {
   commandParams: HandleCommandsParams;
   targets: PrivateCommandRouteTarget[];
@@ -105,6 +110,7 @@ export async function deliverPrivateCommandReply(params: {
   return results.some((result) => result.status === "fulfilled" && result.value.ok);
 }
 
+/** Reads the command message thread id from command context. */
 export function readCommandMessageThreadId(params: HandleCommandsParams): string | undefined {
   return typeof params.ctx.MessageThreadId === "string" ||
     typeof params.ctx.MessageThreadId === "number"
@@ -112,6 +118,7 @@ export function readCommandMessageThreadId(params: HandleCommandsParams): string
     : undefined;
 }
 
+/** Reads the best delivery target for command route resolution. */
 export function readCommandDeliveryTarget(params: HandleCommandsParams): string | undefined {
   return (
     normalizeOptionalString(params.ctx.OriginatingTo) ??
diff --git a/src/auto-reply/reply/commands-status.ts b/src/auto-reply/reply/commands-status.ts
index c791ffb3aedc..b7a1a3d497b2 100644
--- a/src/auto-reply/reply/commands-status.ts
+++ b/src/auto-reply/reply/commands-status.ts
@@ -1,3 +1,4 @@
+/** Builds /status replies using the command's authorized channel context. */
 import { logVerbose } from "../../globals.js";
 import { buildStatusText } from "../../status/status-text.js";
 import type { BuildStatusTextParams } from "../../status/status-text.types.js";
@@ -9,6 +10,7 @@ type BuildStatusReplyParams = Omit<BuildStatusTextParams, "statusChannel"> & {
   command: CommandContext;
 };
 
+/** Builds a status reply or suppresses unauthorized status requests. */
 export async function buildStatusReply(
   params: BuildStatusReplyParams,
 ): Promise<ReplyPayload | undefined> {
diff --git a/src/auto-reply/reply/commands-subagents-text.ts b/src/auto-reply/reply/commands-subagents-text.ts
index 159f0e31203a..b48ecb79f3b0 100644
--- a/src/auto-reply/reply/commands-subagents-text.ts
+++ b/src/auto-reply/reply/commands-subagents-text.ts
@@ -1,3 +1,4 @@
+/** Text extraction helpers for subagent command output. */
 import { sanitizeTextContent } from "../../agents/tools/chat-history-text.js";
 import { extractTextFromChatContent } from "../../shared/chat-content.js";
 
diff --git a/src/auto-reply/reply/directive-handling.model-selection.ts b/src/auto-reply/reply/directive-handling.model-selection.ts
index 811f6b432054..e972921c9146 100644
--- a/src/auto-reply/reply/directive-handling.model-selection.ts
+++ b/src/auto-reply/reply/directive-handling.model-selection.ts
@@ -1,3 +1,4 @@
+/** Resolves /model directive selections and auth profile overrides. */
 import { ensureAuthProfileStore } from "../../agents/auth-profiles.js";
 import { isModelKeyAllowedBySet } from "../../agents/model-selection-shared.js";
 import {
@@ -44,6 +45,7 @@ function resolveStoredNumericProfileModelDirective(params: { raw: string; agentD
   return { modelRaw, profileId, profileProvider: profile.provider };
 }
 
+/** Resolves the requested model/profile override from parsed inline directives. */
 export function resolveModelSelectionFromDirective(params: {
   directives: InlineDirectives;
   cfg: OpenClawConfig;
diff --git a/src/auto-reply/reply/directive-handling.queue-validation.ts b/src/auto-reply/reply/directive-handling.queue-validation.ts
index 7b1504a4a8e7..a701ae28b0a2 100644
--- a/src/auto-reply/reply/directive-handling.queue-validation.ts
+++ b/src/auto-reply/reply/directive-handling.queue-validation.ts
@@ -1,3 +1,4 @@
+/** Validation and status handling for /queue directives. */
 import type { SessionEntry } from "../../config/sessions.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { ReplyPayload } from "../types.js";
diff --git a/src/auto-reply/reply/effective-reply-route.ts b/src/auto-reply/reply/effective-reply-route.ts
index c2a8e8b975dc..ea68d1be6a42 100644
--- a/src/auto-reply/reply/effective-reply-route.ts
+++ b/src/auto-reply/reply/effective-reply-route.ts
@@ -1,19 +1,23 @@
+/** Resolves the effective reply route from current context and persisted session route. */
 import type { SessionEntry } from "../../config/sessions/types.js";
 import { stringifyRouteThreadId } from "../../plugin-sdk/channel-route.js";
 import type { InputProvenance } from "../../sessions/input-provenance.js";
 import { INTERNAL_MESSAGE_CHANNEL, normalizeMessageChannel } from "../../utils/message-channel.js";
 import type { FinalizedMsgContext } from "../templating.js";
 
+/** Current finalized context fields used for reply route resolution. */
 export type EffectiveReplyRouteContext = Pick<
   FinalizedMsgContext,
   "Provider" | "Surface" | "OriginatingChannel" | "OriginatingTo" | "AccountId" | "InputProvenance"
 >;
 
+/** Persisted session fields used as route fallback/inheritance. */
 export type EffectiveReplyRouteEntry = Pick<
   SessionEntry,
   "deliveryContext" | "lastChannel" | "lastTo" | "lastAccountId" | "route"
 >;
 
+/** Effective channel target selected for source reply delivery. */
 export type EffectiveReplyRoute = {
   channel?: string;
   to?: string;
@@ -22,6 +26,7 @@ export type EffectiveReplyRoute = {
   inheritedExternalRoute?: boolean;
 };
 
+/** Returns true for synthetic providers that should not define a user channel route. */
 export function isSystemEventProvider(provider?: string): boolean {
   return provider === "heartbeat" || provider === "cron-event" || provider === "exec-event";
 }
@@ -53,6 +58,7 @@ function resolveTrustedInheritedThreadId(
   return undefined;
 }
 
+/** Resolves current, inherited, or persisted reply route for a session turn. */
 export function resolveEffectiveReplyRoute(params: {
   ctx: EffectiveReplyRouteContext;
   entry?: EffectiveReplyRouteEntry;
diff --git a/src/auto-reply/reply/followup-delivery.ts b/src/auto-reply/reply/followup-delivery.ts
index 46f8c2333c5c..88dead2cf8b6 100644
--- a/src/auto-reply/reply/followup-delivery.ts
+++ b/src/auto-reply/reply/followup-delivery.ts
@@ -1,3 +1,4 @@
+/** Prepares queued follow-up payloads for source-channel delivery. */
 import type { MessagingToolSend } from "../../agents/embedded-agent-messaging.types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { stripHeartbeatToken } from "../heartbeat.js";
@@ -23,6 +24,7 @@ function hasReplyPayloadMedia(payload: ReplyPayload): boolean {
   return Array.isArray(payload.mediaUrls) && payload.mediaUrls.some((url) => url.trim().length > 0);
 }
 
+/** Strips heartbeat tokens, applies threading, and dedupes message-tool sends. */
 export function resolveFollowupDeliveryPayloads(params: {
   cfg: OpenClawConfig;
   payloads: ReplyPayload[];
diff --git a/src/auto-reply/reply/get-reply-inline-actions.ts b/src/auto-reply/reply/get-reply-inline-actions.ts
index 250f2cdb6a83..a8ee0c8e9f4d 100644
--- a/src/auto-reply/reply/get-reply-inline-actions.ts
+++ b/src/auto-reply/reply/get-reply-inline-actions.ts
@@ -1,3 +1,4 @@
+/** Handles inline slash commands, skill invocations, and abort actions before model runs. */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -120,6 +121,7 @@ function isMentionOnlyResidualText(text: string, wasMentioned: boolean | undefin
   return /^(?:<@[!&]?[A-Za-z0-9._:-]+>|<!(?:here|channel|everyone)>|[:,.!?-]|\s)+$/u.test(trimmed);
 }
 
+/** Result of attempting to handle an inbound message as an inline action. */
 export type InlineActionResult =
   | { kind: "reply"; reply: ReplyPayload | ReplyPayload[] | undefined }
   | {
@@ -177,6 +179,7 @@ function extractBlockedToolReason(result: unknown): string | null {
   return typeof reason === "string" && reason.trim() ? reason.trim() : null;
 }
 
+/** Handles inline actions or returns continue when the message should become a model turn. */
 export async function handleInlineActions(params: {
   ctx: MsgContext;
   sessionCtx: TemplateContext;
diff --git a/src/auto-reply/reply/reply-timing-tracker.ts b/src/auto-reply/reply/reply-timing-tracker.ts
index e3f4ced5cca2..a0d0fe9f1fcb 100644
--- a/src/auto-reply/reply/reply-timing-tracker.ts
+++ b/src/auto-reply/reply/reply-timing-tracker.ts
@@ -1,3 +1,4 @@
+/** Lightweight reply-stage profiler for slow-turn diagnostics. */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { isDiagnosticFlagEnabled } from "../../infra/diagnostic-flags.js";
 
diff --git a/src/auto-reply/reply/runtime-policy-session-key.ts b/src/auto-reply/reply/runtime-policy-session-key.ts
index fc09da00f55d..5252f8108106 100644
--- a/src/auto-reply/reply/runtime-policy-session-key.ts
+++ b/src/auto-reply/reply/runtime-policy-session-key.ts
@@ -1,3 +1,4 @@
+/** Resolves runtime policy session keys distinct from transcript session keys. */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
@@ -84,6 +85,7 @@ function isMainSessionAlias(params: {
 }
 
 /** Resolves the session key used for runtime policy checks and direct-message scoping. */
+/** Resolves the session key used for sandbox/tool/runtime policy lookups. */
 export function resolveRuntimePolicySessionKey(params: {
   cfg?: OpenClawConfig;
   ctx?: RuntimePolicyContext;
diff --git a/src/auto-reply/reply/session-fork.ts b/src/auto-reply/reply/session-fork.ts
index 47bd07ec3acd..228bc447a2ee 100644
--- a/src/auto-reply/reply/session-fork.ts
+++ b/src/auto-reply/reply/session-fork.ts
@@ -1,3 +1,4 @@
+/** Public session-fork facade with parent-size admission checks. */
 import type { SessionEntry } from "../../config/sessions/types.js";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 
@@ -9,6 +10,7 @@ import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 const DEFAULT_PARENT_FORK_MAX_TOKENS = 100_000;
 const sessionForkRuntimeLoader = createLazyImportLoader(() => import("./session-fork.runtime.js"));
 
+/** Decision for whether a child session should fork parent context or start isolated. */
 export type ParentForkDecision =
   | {
       status: "fork";
@@ -37,6 +39,7 @@ function formatParentForkTooLargeMessage(params: {
   );
 }
 
+/** Decides whether parent context is small enough to fork into a child session. */
 export async function resolveParentForkDecision(params: {
   parentEntry: SessionEntry;
   storePath: string;
@@ -62,6 +65,7 @@ export async function resolveParentForkDecision(params: {
   };
 }
 
+/** Forks a new session transcript from a parent session. */
 export async function forkSessionFromParent(params: {
   parentEntry: SessionEntry;
   agentId: string;
diff --git a/src/auto-reply/reply/session-reset-cleanup.ts b/src/auto-reply/reply/session-reset-cleanup.ts
index 3e03b8f6aad3..4d74836023bf 100644
--- a/src/auto-reply/reply/session-reset-cleanup.ts
+++ b/src/auto-reply/reply/session-reset-cleanup.ts
@@ -1,3 +1,4 @@
+/** Clears reset-related queues and system events for session keys. */
 import { drainSystemEventEntries } from "../../infra/system-events.js";
 import { clearSessionQueues, type ClearSessionQueueResult } from "./queue/cleanup.js";
 
diff --git a/src/auto-reply/reply/session-usage.ts b/src/auto-reply/reply/session-usage.ts
index ffd7a28bc4c7..36aa790e5b62 100644
--- a/src/auto-reply/reply/session-usage.ts
+++ b/src/auto-reply/reply/session-usage.ts
@@ -1,3 +1,4 @@
+/** Persists usage, cost, model, and CLI session metadata after reply runs. */
 import {
   clearCliSession,
   setCliSessionBinding,
@@ -92,6 +93,7 @@ function estimateSessionRunCostUsd(params: {
   return resolveNonNegativeNumber(estimateUsageCost({ usage: params.usage, cost }));
 }
 
+/** Persists usage accounting and selected runtime metadata to the session store. */
 export async function persistSessionUsageUpdate(params: {
   storePath?: string;
   sessionKey?: string;