From dc3f2bd1d9273f150ede6992cf92f04434953e4f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 03:03:13 -0400
Subject: [PATCH] docs: document infra process helpers

---
 src/infra/approval-native-target-key.test.ts           | 1 +
 src/infra/binaries.test.ts                             | 1 +
 src/infra/boundary-path.test.ts                        | 1 +
 src/infra/build-stamp.test.ts                          | 1 +
 src/infra/clipboard.ts                                 | 1 +
 src/infra/exec-approval-reply.test.ts                  | 1 +
 src/infra/executable-path.ts                           | 1 +
 src/infra/heartbeat-events.test.ts                     | 1 +
 src/infra/heartbeat-reason.test.ts                     | 1 +
 src/infra/heartbeat-runner.test-utils.ts               | 1 +
 src/infra/host-env-security.ts                         | 1 +
 src/infra/install-mode-options.test.ts                 | 1 +
 src/infra/is-main.test.ts                              | 1 +
 src/infra/npm-registry-spec.test.ts                    | 1 +
 src/infra/package-tag.test.ts                          | 1 +
 src/infra/provider-usage.fetch.gemini.test.ts          | 1 +
 src/infra/provider-usage.test.ts                       | 1 +
 src/infra/push-web.ts                                  | 1 +
 src/infra/restart-coordinator.ts                       | 1 +
 src/infra/sqlite-pragma.test-support.ts                | 1 +
 src/infra/ssh-config.test.ts                           | 1 +
 src/infra/system-run-approval-context.test.ts          | 1 +
 src/infra/unhandled-rejections.fatal-detection.test.ts | 1 +
 src/infra/watch-node.test.ts                           | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/infra/approval-native-target-key.test.ts b/src/infra/approval-native-target-key.test.ts
index fc6fca40bd2..265328f9ab0 100644
--- a/src/infra/approval-native-target-key.test.ts
+++ b/src/infra/approval-native-target-key.test.ts
@@ -1,3 +1,4 @@
+// Tests native approval target key generation.
 import { describe, expect, it } from "vitest";
 import { buildChannelApprovalNativeTargetKey } from "./approval-native-target-key.js";
 
diff --git a/src/infra/binaries.test.ts b/src/infra/binaries.test.ts
index 425a2696fbf..877279ef8ac 100644
--- a/src/infra/binaries.test.ts
+++ b/src/infra/binaries.test.ts
@@ -1,3 +1,4 @@
+// Tests bundled binary discovery and version command helpers.
 import { describe, expect, it, vi } from "vitest";
 import type { runExec } from "../process/exec.js";
 import type { RuntimeEnv } from "../runtime.js";
diff --git a/src/infra/boundary-path.test.ts b/src/infra/boundary-path.test.ts
index 4d45a2c7cf3..cd7569eab94 100644
--- a/src/infra/boundary-path.test.ts
+++ b/src/infra/boundary-path.test.ts
@@ -1,3 +1,4 @@
+// Tests path boundary enforcement for safe file access.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/infra/build-stamp.test.ts b/src/infra/build-stamp.test.ts
index 8b0e9748ca2..882a0d1967f 100644
--- a/src/infra/build-stamp.test.ts
+++ b/src/infra/build-stamp.test.ts
@@ -1,3 +1,4 @@
+// Tests build stamp file parsing and fallback behavior.
 import fs from "node:fs/promises";
 import { describe, expect, it } from "vitest";
 import { writeBuildStamp } from "../../scripts/build-stamp.mjs";
diff --git a/src/infra/clipboard.ts b/src/infra/clipboard.ts
index 46ed96bff17..d37e968d64b 100644
--- a/src/infra/clipboard.ts
+++ b/src/infra/clipboard.ts
@@ -1,3 +1,4 @@
+// Reads and writes clipboard text through platform command helpers.
 import { runCommandWithTimeout } from "../process/exec.js";
 import { isWSL2Sync } from "./wsl.js";
 
diff --git a/src/infra/exec-approval-reply.test.ts b/src/infra/exec-approval-reply.test.ts
index 4afa6541e8c..263c7b1b1e1 100644
--- a/src/infra/exec-approval-reply.test.ts
+++ b/src/infra/exec-approval-reply.test.ts
@@ -1,3 +1,4 @@
+// Tests execution approval reply text and decision formatting.
 import { describe, expect, it, vi } from "vitest";
 import type { ReplyPayload } from "../auto-reply/types.js";
 
diff --git a/src/infra/executable-path.ts b/src/infra/executable-path.ts
index 951d875fb4f..39407a86058 100644
--- a/src/infra/executable-path.ts
+++ b/src/infra/executable-path.ts
@@ -1,3 +1,4 @@
+// Resolves executable paths from PATH and platform-specific install locations.
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/infra/heartbeat-events.test.ts b/src/infra/heartbeat-events.test.ts
index 98bb8f541bb..baa0553c8bb 100644
--- a/src/infra/heartbeat-events.test.ts
+++ b/src/infra/heartbeat-events.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat event emission and listener cleanup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   emitHeartbeatEvent,
diff --git a/src/infra/heartbeat-reason.test.ts b/src/infra/heartbeat-reason.test.ts
index 05f5eb4405d..d6743618131 100644
--- a/src/infra/heartbeat-reason.test.ts
+++ b/src/infra/heartbeat-reason.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat reason formatting and normalization.
 import { describe, expect, it } from "vitest";
 import { normalizeHeartbeatWakeReason } from "./heartbeat-reason.js";
 
diff --git a/src/infra/heartbeat-runner.test-utils.ts b/src/infra/heartbeat-runner.test-utils.ts
index c983471418e..1b6e6e09f8f 100644
--- a/src/infra/heartbeat-runner.test-utils.ts
+++ b/src/infra/heartbeat-runner.test-utils.ts
@@ -1,3 +1,4 @@
+// Shared heartbeat runner fixtures for infra tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/host-env-security.ts b/src/infra/host-env-security.ts
index 46d68b4299a..e48347f0672 100644
--- a/src/infra/host-env-security.ts
+++ b/src/infra/host-env-security.ts
@@ -1,3 +1,4 @@
+// Filters host environment variables before passing them to runtimes.
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { HOST_ENV_SECURITY_POLICY } from "./host-env-security-policy.js";
 import { markOpenClawExecEnv } from "./openclaw-exec-env.js";
diff --git a/src/infra/install-mode-options.test.ts b/src/infra/install-mode-options.test.ts
index 6fd450ee370..02b092cf49a 100644
--- a/src/infra/install-mode-options.test.ts
+++ b/src/infra/install-mode-options.test.ts
@@ -1,3 +1,4 @@
+// Tests install mode option parsing for setup commands.
 import { describe, expect, it } from "vitest";
 import {
   resolveInstallModeOptions,
diff --git a/src/infra/is-main.test.ts b/src/infra/is-main.test.ts
index 6c7b529f84e..63d5156e264 100644
--- a/src/infra/is-main.test.ts
+++ b/src/infra/is-main.test.ts
@@ -1,3 +1,4 @@
+// Tests module main-entry detection helpers.
 import { describe, expect, it, vi } from "vitest";
 import { isMainModule } from "./is-main.js";
 
diff --git a/src/infra/npm-registry-spec.test.ts b/src/infra/npm-registry-spec.test.ts
index 4bd369b4642..87ce5c7807a 100644
--- a/src/infra/npm-registry-spec.test.ts
+++ b/src/infra/npm-registry-spec.test.ts
@@ -1,3 +1,4 @@
+// Tests npm registry spec parsing for packages, tags, and versions.
 import { describe, expect, it } from "vitest";
 import {
   compareOpenClawReleaseVersions,
diff --git a/src/infra/package-tag.test.ts b/src/infra/package-tag.test.ts
index 526e7cdc7fd..e7ac1f09505 100644
--- a/src/infra/package-tag.test.ts
+++ b/src/infra/package-tag.test.ts
@@ -1,3 +1,4 @@
+// Tests package tag parsing and stable release tag behavior.
 import { describe, expect, it } from "vitest";
 import { normalizePackageTagInput } from "./package-tag.js";
 
diff --git a/src/infra/provider-usage.fetch.gemini.test.ts b/src/infra/provider-usage.fetch.gemini.test.ts
index 864dff08c66..4fc78f399d7 100644
--- a/src/infra/provider-usage.fetch.gemini.test.ts
+++ b/src/infra/provider-usage.fetch.gemini.test.ts
@@ -1,3 +1,4 @@
+// Tests Gemini provider usage fetch normalization.
 import { describe, expect, it } from "vitest";
 import { createProviderUsageFetch, makeResponse } from "../test-utils/provider-usage-fetch.js";
 import { fetchGeminiUsage } from "./provider-usage.fetch.gemini.js";
diff --git a/src/infra/provider-usage.test.ts b/src/infra/provider-usage.test.ts
index b50eaf10963..210b0e142a4 100644
--- a/src/infra/provider-usage.test.ts
+++ b/src/infra/provider-usage.test.ts
@@ -1,3 +1,4 @@
+// Tests provider usage aggregation and formatting.
 import { beforeEach, describe, expect, it } from "vitest";
 import { createProviderUsageFetch } from "../test-utils/provider-usage-fetch.js";
 import {
diff --git a/src/infra/push-web.ts b/src/infra/push-web.ts
index 5fc8ca4576b..f16bce0fb75 100644
--- a/src/infra/push-web.ts
+++ b/src/infra/push-web.ts
@@ -1,3 +1,4 @@
+// Stores and verifies web push subscriptions and delivery payloads.
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
diff --git a/src/infra/restart-coordinator.ts b/src/infra/restart-coordinator.ts
index 66e90af2b75..8e69f9110b9 100644
--- a/src/infra/restart-coordinator.ts
+++ b/src/infra/restart-coordinator.ts
@@ -1,3 +1,4 @@
+// Coordinates restart requests around active embedded agent runs.
 import { getActiveEmbeddedRunCount } from "../agents/embedded-agent-runner/run-state.js";
 import { getTotalPendingReplies } from "../auto-reply/reply/dispatcher-registry.js";
 import { getTotalQueueSize } from "../process/command-queue.js";
diff --git a/src/infra/sqlite-pragma.test-support.ts b/src/infra/sqlite-pragma.test-support.ts
index 23df5fcd050..6a2d3914d75 100644
--- a/src/infra/sqlite-pragma.test-support.ts
+++ b/src/infra/sqlite-pragma.test-support.ts
@@ -1,3 +1,4 @@
+// Test helper for reading SQLite pragma state.
 import type { DatabaseSync } from "node:sqlite";
 
 // SQLite pragma test helpers normalize node:sqlite bigint/number outputs.
diff --git a/src/infra/ssh-config.test.ts b/src/infra/ssh-config.test.ts
index c9f32385c54..6d46c2b876b 100644
--- a/src/infra/ssh-config.test.ts
+++ b/src/infra/ssh-config.test.ts
@@ -1,3 +1,4 @@
+// Tests SSH config parsing and spawned command options.
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { beforeAll, describe, expect, it, vi } from "vitest";
diff --git a/src/infra/system-run-approval-context.test.ts b/src/infra/system-run-approval-context.test.ts
index bb6efe9b900..e5e0d352fd7 100644
--- a/src/infra/system-run-approval-context.test.ts
+++ b/src/infra/system-run-approval-context.test.ts
@@ -1,3 +1,4 @@
+// Tests system-run approval context construction.
 import { describe, expect, test } from "vitest";
 import {
   parsePreparedSystemRunPayload,
diff --git a/src/infra/unhandled-rejections.fatal-detection.test.ts b/src/infra/unhandled-rejections.fatal-detection.test.ts
index 841a8162160..9be10ebd6a4 100644
--- a/src/infra/unhandled-rejections.fatal-detection.test.ts
+++ b/src/infra/unhandled-rejections.fatal-detection.test.ts
@@ -1,3 +1,4 @@
+// Tests fatal unhandled rejection detection in process bootstrap.
 import process from "node:process";
 import { describe, it, expect, vi, beforeAll, afterAll, beforeEach, afterEach } from "vitest";
 
diff --git a/src/infra/watch-node.test.ts b/src/infra/watch-node.test.ts
index 018b6f1f78e..d572a58f4c4 100644
--- a/src/infra/watch-node.test.ts
+++ b/src/infra/watch-node.test.ts
@@ -1,3 +1,4 @@
+// Tests watched node process restart and hashing behavior.
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import fs from "node:fs";