docs: document provider policy tests

src/agents/owner-display.test.ts

@@ -1,3 +1,4 @@
+// Verifies owner display hashing uses a dedicated secret and raw mode disables it.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { ensureOwnerDisplaySecret, resolveOwnerDisplaySetting } from "./owner-display.js";
@@ -18,6 +19,7 @@ describe("resolveOwnerDisplaySetting", () => {
   });
 
   it("does not fall back to gateway tokens when hash secret is missing", () => {
+    // Gateway auth tokens are unrelated secrets and must never seed owner hashes.
     const cfg = {
       commands: {
         ownerDisplay: "hash",

src/agents/path-policy.test.ts

@@ -1,3 +1,4 @@
+// Verifies workspace-relative path policy across POSIX and Windows semantics.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { withMockedWindowsPlatform } from "../test-utils/vitest-spies.js";
 
@@ -11,6 +12,7 @@ import { toRelativeWorkspacePath } from "./path-policy.js";
 
 describe("toRelativeWorkspacePath (windows semantics)", () => {
   beforeEach(() => {
+    // Sandbox input resolution is not under test; return normalized input paths directly.
     resolveSandboxInputPathMock.mockReset();
     resolveSandboxInputPathMock.mockImplementation((filePath: string) => filePath);
   });

src/agents/plugin-text-transforms.test.ts

@@ -1,3 +1,4 @@
+// Verifies plugin text transforms rewrite prompts and streamed assistant output.
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import {
   createAssistantMessageEventStream,
@@ -20,6 +21,7 @@ const model = {
 } as Model<"openai-responses">;
 
 function makeAssistantMessage(text: string): AssistantMessage {
+  // Output transform tests need a complete assistant message with visible text.
   return {
     role: "assistant",
     content: [{ type: "text", text }],
@@ -106,6 +108,7 @@ describe("plugin text transforms", () => {
   });
 
   it("wraps stream functions with inbound and outbound replacements", async () => {
+    // The wrapper mutates text-only blocks while preserving non-text content.
     let capturedContext: Context | undefined;
     const baseStreamFn: StreamFn = (_model, context) => {
       capturedContext = context;

src/agents/prompt-composition.test.ts

@@ -1,3 +1,4 @@
+// Verifies prompt composition invariants across generated agent scenarios.
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import {
   createPromptCompositionScenarios,
@@ -7,6 +8,7 @@ import {
 type ScenarioFixture = Awaited<ReturnType<typeof createPromptCompositionScenarios>>;
 
 function getTurn(scenario: PromptScenario, id: string) {
+  // Scenario assertions use named turns so failures identify the prompt boundary.
   const turn = scenario.turns.find((entry) => entry.id === id);
   if (!turn) {
     throw new Error(`expected turn ${scenario.scenario}:${id}`);
@@ -23,6 +25,7 @@ function getScenario(fixture: ScenarioFixture, id: string): PromptScenario {
 }
 
 function countOccurrences(text: string, needle: string): number {
+  // Avoid regex escaping when checking exact prompt-body duplication.
   if (!needle) {
     return 0;
   }

src/agents/provider-api-families.test.ts

@@ -1,3 +1,4 @@
+// Verifies provider API family helpers gate GPT parallel tool-call payloads.
 import { describe, expect, it } from "vitest";
 import { supportsGptParallelToolCallsPayload } from "./provider-api-families.js";
 

src/agents/provider-attribution.test.ts

@@ -1,6 +1,8 @@
+// Verifies provider attribution headers and endpoint classification policies.
 import { describe, expect, it, vi } from "vitest";
 
 function expectRecordFields(record: unknown, expected: Record<string, unknown>) {
+  // Policy helpers return broad records; assertions pin only the relevant fields.
   if (!record || typeof record !== "object") {
     throw new Error("Expected record");
   }
@@ -13,6 +15,7 @@ function expectRecordFields(record: unknown, expected: Record<string, unknown>)
 
 const providerEndpointPlugins = vi.hoisted(() => [
   {
+    // Mirrors manifest-declared endpoint metadata without loading real plugins.
     providerEndpoints: [
       { endpointClass: "openai-public", hosts: ["api.openai.com"] },
       { endpointClass: "openai", hosts: ["chatgpt.com"] },
@@ -239,6 +242,7 @@ describe("provider attribution", () => {
   });
 
   it("lists the current attribution support matrix", () => {
+    // Matrix order is user-facing evidence for docs/review summaries.
     expect(
       listProviderAttributionPolicies({ OPENCLAW_VERSION: "2026.3.22" }).map((policy) => [
         policy.provider,