docs: document infra process helpers

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";
 

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";

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";

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";

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";
 

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";
 

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";

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,

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";
 

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";

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";

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,

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";
 

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,

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";
 

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";

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 {

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";

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";

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.

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";

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,

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";
 

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";