diff --git a/src/infra/approval-errors.ts b/src/infra/approval-errors.ts
index 76f2bd71a2e1..c8004102ed99 100644
--- a/src/infra/approval-errors.ts
+++ b/src/infra/approval-errors.ts
@@ -1,3 +1,4 @@
+// Detects approval-not-found errors across gateway response shapes.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 const INVALID_REQUEST = "INVALID_REQUEST";
diff --git a/src/infra/approval-native-delivery.test.ts b/src/infra/approval-native-delivery.test.ts
index 0bcb6ce1a504..36a22b9a374e 100644
--- a/src/infra/approval-native-delivery.test.ts
+++ b/src/infra/approval-native-delivery.test.ts
@@ -1,3 +1,4 @@
+// Covers native approval delivery planning.
 import { describe, expect, it } from "vitest";
 import type { ChannelApprovalNativeAdapter } from "../channels/plugins/types.adapters.js";
 import { resolveChannelNativeApprovalDeliveryPlan } from "./approval-native-delivery.js";
diff --git a/src/infra/approval-request-filters.ts b/src/infra/approval-request-filters.ts
index 4e70b367092a..9ef0183d65b6 100644
--- a/src/infra/approval-request-filters.ts
+++ b/src/infra/approval-request-filters.ts
@@ -1,3 +1,4 @@
+// Filters approval requests by agent and session patterns.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { parseAgentSessionKey } from "../routing/session-key.js";
 import { compileSafeRegex, testRegexWithBoundedInput } from "../security/safe-regex.js";
diff --git a/src/infra/command-carriers.ts b/src/infra/command-carriers.ts
index f3f29747f938..b091a4e82b8a 100644
--- a/src/infra/command-carriers.ts
+++ b/src/infra/command-carriers.ts
@@ -1,3 +1,4 @@
+// Identifies wrapper commands that can carry hidden command payloads.
 import { splitShellArgs } from "../utils/shell-argv.js";
 import { normalizeExecutableToken } from "./exec-wrapper-tokens.js";
 import { parseInlineOptionToken } from "./inline-option-token.js";
diff --git a/src/infra/dedupe.ts b/src/infra/dedupe.ts
index 46a1914da979..6381e345686c 100644
--- a/src/infra/dedupe.ts
+++ b/src/infra/dedupe.ts
@@ -1,3 +1,4 @@
+// Provides small process-local dedupe caches.
 import { resolveGlobalSingleton } from "../shared/global-singleton.js";
 import { pruneMapToMaxSize } from "./map-size.js";
 import { resolveNonNegativeIntegerOption } from "./numeric-options.js";
diff --git a/src/infra/disk-space.test.ts b/src/infra/disk-space.test.ts
index 596afd5af139..269d28008ebd 100644
--- a/src/infra/disk-space.test.ts
+++ b/src/infra/disk-space.test.ts
@@ -1,3 +1,4 @@
+// Covers disk-space formatting and warning generation.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/exec-safe-bin-policy.test.ts b/src/infra/exec-safe-bin-policy.test.ts
index a5d21f9d9d1c..5befff169918 100644
--- a/src/infra/exec-safe-bin-policy.test.ts
+++ b/src/infra/exec-safe-bin-policy.test.ts
@@ -1,3 +1,4 @@
+// Covers safe-bin policy profiles, validation, and generated docs text.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/infra/exec-wrapper-tokens.ts b/src/infra/exec-wrapper-tokens.ts
index 27fa39a1987d..c6f3412b08ee 100644
--- a/src/infra/exec-wrapper-tokens.ts
+++ b/src/infra/exec-wrapper-tokens.ts
@@ -1,3 +1,4 @@
+// Normalizes executable tokens used by wrapper and policy analysis.
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
diff --git a/src/infra/gateway-process-argv.ts b/src/infra/gateway-process-argv.ts
index 1681b08a3968..bd68c1550136 100644
--- a/src/infra/gateway-process-argv.ts
+++ b/src/infra/gateway-process-argv.ts
@@ -1,3 +1,4 @@
+// Parses gateway process command lines for process discovery.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 
diff --git a/src/infra/heartbeat-events-filter.test.ts b/src/infra/heartbeat-events-filter.test.ts
index 6ebec95ec44d..461773046dea 100644
--- a/src/infra/heartbeat-events-filter.test.ts
+++ b/src/infra/heartbeat-events-filter.test.ts
@@ -1,3 +1,4 @@
+// Covers heartbeat event prompt filtering.
 import { describe, expect, it } from "vitest";
 import {
   buildCronEventPrompt,
diff --git a/src/infra/heartbeat-visibility.ts b/src/infra/heartbeat-visibility.ts
index 89d460dd42fc..624bb12f0765 100644
--- a/src/infra/heartbeat-visibility.ts
+++ b/src/infra/heartbeat-visibility.ts
@@ -1,3 +1,4 @@
+// Resolves heartbeat visibility toggles across config precedence levels.
 import type { ChannelHeartbeatVisibilityConfig } from "../config/types.channels.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { GatewayMessageChannel } from "../utils/message-channel.js";
diff --git a/src/infra/install-source-utils.test.ts b/src/infra/install-source-utils.test.ts
index 81eed80661ae..a061ce2af013 100644
--- a/src/infra/install-source-utils.test.ts
+++ b/src/infra/install-source-utils.test.ts
@@ -1,3 +1,4 @@
+// Covers npm install source packing and archive path resolution.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/infra/map-size.test.ts b/src/infra/map-size.test.ts
index 28251d0b219b..c644858910e5 100644
--- a/src/infra/map-size.test.ts
+++ b/src/infra/map-size.test.ts
@@ -1,3 +1,4 @@
+// Covers bounded map pruning.
 import { describe, expect, it } from "vitest";
 import { pruneMapToMaxSize } from "./map-size.js";
 
diff --git a/src/infra/node-pairing-authz.ts b/src/infra/node-pairing-authz.ts
index 6e035db45738..8ed0a023a9ec 100644
--- a/src/infra/node-pairing-authz.ts
+++ b/src/infra/node-pairing-authz.ts
@@ -1,3 +1,4 @@
+// Maps node pairing command declarations to required operator scopes.
 import { NODE_SYSTEM_RUN_COMMANDS } from "./node-commands.js";
 
 /** Operator scopes required to approve a pending node pairing surface. */
diff --git a/src/infra/package-json.ts b/src/infra/package-json.ts
index c40251918cda..4607b76f93de 100644
--- a/src/infra/package-json.ts
+++ b/src/infra/package-json.ts
@@ -1,3 +1,4 @@
+// Reads package.json metadata needed by install and update flows.
 import path from "node:path";
 import { normalizeNullableString as normalizeString } from "@openclaw/normalization-core/string-coerce";
 import { tryReadJson } from "./json-files.js";
diff --git a/src/infra/path-env.ts b/src/infra/path-env.ts
index 31f1bd652ba4..d6b56a5ebae1 100644
--- a/src/infra/path-env.ts
+++ b/src/infra/path-env.ts
@@ -1,3 +1,4 @@
+// Builds PATH values for OpenClaw child processes.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/plugin-approvals.ts b/src/infra/plugin-approvals.ts
index 110a026da51e..b6a1748a5ba1 100644
--- a/src/infra/plugin-approvals.ts
+++ b/src/infra/plugin-approvals.ts
@@ -1,3 +1,4 @@
+// Defines plugin approval request/resolution payloads and actions.
 import type { ExecApprovalDecision } from "./exec-approvals.js";
 
 // Plugin approval types and renderers mirror exec approval decisions while
diff --git a/src/infra/plugin-install-path-warnings.test.ts b/src/infra/plugin-install-path-warnings.test.ts
index ed65705307ef..70270083d4d8 100644
--- a/src/infra/plugin-install-path-warnings.test.ts
+++ b/src/infra/plugin-install-path-warnings.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin install path warning detection and copy.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { withTempHome } from "openclaw/plugin-sdk/test-env";
diff --git a/src/infra/provider-usage.fetch.codex.test.ts b/src/infra/provider-usage.fetch.codex.test.ts
index eb055c70032d..dd58c4154957 100644
--- a/src/infra/provider-usage.fetch.codex.test.ts
+++ b/src/infra/provider-usage.fetch.codex.test.ts
@@ -1,3 +1,4 @@
+// Covers Codex provider usage fetch parsing.
 import { describe, expect, it } from "vitest";
 import { createProviderUsageFetch, makeResponse } from "../test-utils/provider-usage-fetch.js";
 import { fetchCodexUsage } from "./provider-usage.fetch.codex.js";
diff --git a/src/infra/provider-usage.load.test.ts b/src/infra/provider-usage.load.test.ts
index 109af75973e7..7fbbe15dbd60 100644
--- a/src/infra/provider-usage.load.test.ts
+++ b/src/infra/provider-usage.load.test.ts
@@ -1,3 +1,4 @@
+// Covers provider usage summary loading across auth and plugin paths.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createProviderUsageFetch, makeResponse } from "../test-utils/provider-usage-fetch.js";
 import {
diff --git a/src/infra/restart-stale-pids.test.ts b/src/infra/restart-stale-pids.test.ts
index 8640fc58ccb8..92b2ff1dc594 100644
--- a/src/infra/restart-stale-pids.test.ts
+++ b/src/infra/restart-stale-pids.test.ts
@@ -1,3 +1,4 @@
+// Covers stale gateway process detection and cleanup.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 // This file primarily tests lsof-based Unix port polling. On Windows,
diff --git a/src/infra/scp-host.ts b/src/infra/scp-host.ts
index 026d98b695e2..f3f6010c12d1 100644
--- a/src/infra/scp-host.ts
+++ b/src/infra/scp-host.ts
@@ -1,3 +1,4 @@
+// Normalizes SCP remote host and path values.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 // SCP host/path normalization rejects shell metacharacters before values are
diff --git a/src/infra/shell-inline-command.test.ts b/src/infra/shell-inline-command.test.ts
index 0e634f8a64df..b534bd9e0d33 100644
--- a/src/infra/shell-inline-command.test.ts
+++ b/src/infra/shell-inline-command.test.ts
@@ -1,3 +1,4 @@
+// Covers shell inline command flag parsing.
 import { describe, expect, it } from "vitest";
 import {
   POSIX_INLINE_COMMAND_FLAGS,
diff --git a/src/infra/system-run-normalize.test.ts b/src/infra/system-run-normalize.test.ts
index 0116ec70873f..a21504e23b02 100644
--- a/src/infra/system-run-normalize.test.ts
+++ b/src/infra/system-run-normalize.test.ts
@@ -1,3 +1,4 @@
+// Covers system-run metadata normalization helpers.
 import { describe, expect, it } from "vitest";
 import { normalizeNonEmptyString, normalizeStringArray } from "./system-run-normalize.js";