From 57ec0b236f6e6de63c247c07e496ff5a4b9ca369 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 15:42:07 -0400
Subject: [PATCH] docs: document runtime utility tests

---
 src/agents/queued-file-writer.test.ts                | 3 +++
 src/agents/realtime-bootstrap-context.test.ts        | 3 +++
 src/agents/responses-image-payload-sanitizer.test.ts | 2 ++
 src/agents/run-cleanup-timeout.test.ts               | 3 +++
 src/agents/runtime-auth-refresh.test.ts              | 1 +
 src/agents/runtime-capabilities.test.ts              | 1 +
 6 files changed, 13 insertions(+)

diff --git a/src/agents/queued-file-writer.test.ts b/src/agents/queued-file-writer.test.ts
index 3dcace3ab6f6..125f5002e689 100644
--- a/src/agents/queued-file-writer.test.ts
+++ b/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");
diff --git a/src/agents/realtime-bootstrap-context.test.ts b/src/agents/realtime-bootstrap-context.test.ts
index bffc5ba2ff5e..540b81cf9412 100644
--- a/src/agents/realtime-bootstrap-context.test.ts
+++ b/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<
diff --git a/src/agents/responses-image-payload-sanitizer.test.ts b/src/agents/responses-image-payload-sanitizer.test.ts
index a93fe6527c6e..f7b77947e8af 100644
--- a/src/agents/responses-image-payload-sanitizer.test.ts
+++ b/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", () => {
diff --git a/src/agents/run-cleanup-timeout.test.ts b/src/agents/run-cleanup-timeout.test.ts
index 436e29b15a25..1e84fc3e5f5c 100644
--- a/src/agents/run-cleanup-timeout.test.ts
+++ b/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({
diff --git a/src/agents/runtime-auth-refresh.test.ts b/src/agents/runtime-auth-refresh.test.ts
index b57eeb27b5cd..cf09c457d0d5 100644
--- a/src/agents/runtime-auth-refresh.test.ts
+++ b/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";
 
diff --git a/src/agents/runtime-capabilities.test.ts b/src/agents/runtime-capabilities.test.ts
index 61a51c6d42f6..1d24658390a2 100644
--- a/src/agents/runtime-capabilities.test.ts
+++ b/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";