docs: document runtime utility tests

src/agents/queued-file-writer.test.ts

@@ -1,3 +1,4 @@
+// Verifies queued file writes keep append logs bounded and symlink-safe.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -7,6 +8,7 @@ import { getQueuedFileWriter, resolveQueuedFileAppendFlags } from "./queued-file
 const tempDirs: string[] = [];
 
 function makeTempDir(): string {
+  // Real temp dirs let symlink and permission checks exercise filesystem behavior.
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-queued-writer-"));
   tempDirs.push(dir);
   return dir;
@@ -56,6 +58,7 @@ describe("getQueuedFileWriter", () => {
   });
 
   it("refuses to append through a symlinked parent directory", async () => {
+    // Parent directory symlinks are as dangerous as leaf-file symlinks.
     const tmpDir = makeTempDir();
     const targetDir = path.join(tmpDir, "target");
     const linkDir = path.join(tmpDir, "link");

src/agents/realtime-bootstrap-context.test.ts

@@ -1,3 +1,4 @@
+// Verifies realtime voice bootstrap context only injects approved profile files.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -14,6 +15,7 @@ async function makeWorkspace(): Promise<string> {
 }
 
 function makeConfig(workspaceDir: string): OpenClawConfig {
+  // Bootstrap context resolves files through the configured default agent workspace.
   return {
     agents: {
       defaults: { workspace: workspaceDir },
@@ -54,6 +56,7 @@ describe("resolveRealtimeBootstrapContextInstructions", () => {
   });
 
   it("ignores unsupported file requests from unchecked callers", async () => {
+    // Runtime callers may pass unchecked file arrays; unsupported files must be filtered.
     const workspaceDir = await makeWorkspace();
     const warnings: string[] = [];
     const uncheckedFiles = ["IDENTITY.md", "AGENTS.md"] as unknown as NonNullable<

src/agents/responses-image-payload-sanitizer.test.ts

@@ -1,7 +1,9 @@
+// Verifies Responses image payloads are canonicalized or replaced before send.
 import { describe, expect, it } from "vitest";
 import { sanitizeResponsesImagePayload } from "./responses-image-payload-sanitizer.js";
 
 const PNG_1X1 =
+  // Valid JPEG-labeled data is sniffed as PNG and normalized to the real MIME type.
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR4nGNgYAAAAAMAASsJTYQAAAAASUVORK5CYII=";
 
 describe("Responses image payload sanitizer", () => {

src/agents/run-cleanup-timeout.test.ts

@@ -1,3 +1,4 @@
+// Verifies agent cleanup steps time out with bounded diagnostic logging.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   AGENT_CLEANUP_STEP_TIMEOUT_MS,
@@ -67,6 +68,7 @@ describe("agent cleanup timeout", () => {
   });
 
   it("includes cleanup timeout details when the cleanup step exposes them", async () => {
+    // Cleanup steps can expose current queue state for timeout diagnostics.
     const cleanup = vi.fn(async () => new Promise<never>(() => {}));
 
     const result = runAgentCleanupStep({
@@ -139,6 +141,7 @@ describe("agent cleanup timeout", () => {
   });
 
   it("bounds cleanup timeout detail errors before logging", async () => {
+    // Diagnostic failures must not produce unbounded logs or fail cleanup.
     const cleanup = vi.fn(async () => new Promise<never>(() => {}));
 
     const result = runAgentCleanupStep({

src/agents/runtime-auth-refresh.test.ts

@@ -1,3 +1,4 @@
+// Verifies runtime auth refresh timers stay within safe JavaScript timer bounds.
 import { describe, expect, it } from "vitest";
 import { clampRuntimeAuthRefreshDelayMs } from "./runtime-auth-refresh.js";
 

src/agents/runtime-capabilities.test.ts

@@ -1,3 +1,4 @@
+// Verifies runtime channel capabilities derived from channel account config.
 import { describe, expect, it } from "vitest";
 import { collectRuntimeChannelCapabilities } from "./runtime-capabilities.js";