diff --git a/src/agents/cli-backends.test.ts b/src/agents/cli-backends.test.ts
index fa2f3e8f4b99..d528c579386f 100644
--- a/src/agents/cli-backends.test.ts
+++ b/src/agents/cli-backends.test.ts
@@ -1,3 +1,4 @@
+/** Tests CLI backend config resolution, normalization, and live-test defaults. */
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type { CliBackendConfig } from "../config/types.js";
@@ -39,6 +40,8 @@ function createBackendEntry(params: {
     context?: CliBackendNormalizeConfigContext,
   ) => CliBackendConfig;
 }) {
+  // Runtime/setup backend entries share most shape; tests build both from one
+  // helper so registry behavior stays aligned.
   return {
     pluginId: params.pluginId,
     source: "test",
@@ -152,6 +155,7 @@ function normalizeTestClaudeArgs(
   args: string[] | undefined,
   permission: { mode?: string; overrideExisting: boolean },
 ): string[] | undefined {
+  // Mirrors Claude backend normalization without loading the bundled runtime.
   if (!args) {
     return permission.mode ? ["--permission-mode", permission.mode] : args;
   }
diff --git a/src/agents/cli-credentials.test.ts b/src/agents/cli-credentials.test.ts
index 6b2906bd5e1b..93a175ade662 100644
--- a/src/agents/cli-credentials.test.ts
+++ b/src/agents/cli-credentials.test.ts
@@ -1,3 +1,4 @@
+/** Tests CLI credential parsing, cache expiry, and safe keychain/file writes. */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -15,6 +16,7 @@ let readCodexCliCredentials: typeof import("./cli-credentials.js").readCodexCliC
 let readGeminiCliCredentialsCached: typeof import("./cli-credentials.js").readGeminiCliCredentialsCached;
 
 function mockExistingClaudeKeychainItem() {
+  // The macOS security CLI returns the whole JSON payload as password data.
   execFileSyncMock.mockImplementation((file: unknown, args: unknown) => {
     const argv = Array.isArray(args) ? args.map(String) : [];
     if (String(file) === "security" && argv.includes("find-generic-password")) {
@@ -49,6 +51,8 @@ async function readCachedClaudeCliCredentials(allowKeychainPrompt: boolean) {
 }
 
 function createJwtWithExp(expSeconds: number): string {
+  // Signature verification is out of scope; expiration extraction only needs a
+  // syntactically valid JWT-like payload.
   const encode = (value: Record<string, unknown>) =>
     Buffer.from(JSON.stringify(value)).toString("base64url");
   return `${encode({ alg: "RS256", typ: "JWT" })}.${encode({ exp: expSeconds })}.signature`;
@@ -67,6 +71,8 @@ function mockClaudeCliCredentialRead() {
 }
 
 function expectFields(value: unknown, expected: Record<string, unknown>): void {
+  // Keeps large credential objects readable while still asserting exact fields
+  // relevant to the branch under test.
   if (!value || typeof value !== "object") {
     throw new Error("expected fields object");
   }
diff --git a/src/agents/cli-output.test.ts b/src/agents/cli-output.test.ts
index 8640c5a5a33a..7875b9c74853 100644
--- a/src/agents/cli-output.test.ts
+++ b/src/agents/cli-output.test.ts
@@ -1,3 +1,4 @@
+/** Tests CLI JSON/JSONL output parsing, streamed deltas, and error extraction. */
 import { describe, expect, it } from "vitest";
 import {
   createCliJsonlStreamingParser,
diff --git a/src/agents/code-mode.test.ts b/src/agents/code-mode.test.ts
index 1416ee41c968..2b6000deec76 100644
--- a/src/agents/code-mode.test.ts
+++ b/src/agents/code-mode.test.ts
@@ -1,3 +1,4 @@
+/** Tests Code Mode tool registration, namespace filtering, and run lifecycle. */
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { isRecord } from "../../packages/normalization-core/src/record-coerce.js";
 import { setPluginToolMeta } from "../plugins/tools.js";
@@ -27,6 +28,7 @@ import {
 import { jsonResult, type AnyAgentTool } from "./tools/common.js";
 
 function fakeTool(name: string, description: string): AnyAgentTool {
+  // Minimal tool shape keeps Code Mode catalog tests runtime-free.
   return {
     name,
     label: name,
@@ -70,6 +72,7 @@ function mcpTool(params: {
   operation?: "tool" | "resources_list" | "resources_read" | "prompts_list" | "prompts_get";
   execute?: AnyAgentTool["execute"];
 }): AnyAgentTool {
+  // MCP metadata drives Code Mode grouping and raw tool routing.
   const tool: AnyAgentTool = {
     name: params.name,
     label: params.toolName,
@@ -138,6 +141,8 @@ async function runUntilCompleted(params: {
   code: string;
   language?: "javascript" | "typescript";
 }) {
+  // Code Mode may return a waiting state before completion; tests poll through
+  // the public wait tool instead of reaching into activeRuns.
   let details = resultDetails(
     await params.execTool.execute("code-call-1", {
       code: params.code,