docs: document infra policy helpers

src/infra/approval-errors.ts

@@ -1,3 +1,4 @@
+// Detects approval-not-found errors across gateway response shapes.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 const INVALID_REQUEST = "INVALID_REQUEST";

src/infra/approval-native-delivery.test.ts

@@ -1,3 +1,4 @@
+// Covers native approval delivery planning.
 import { describe, expect, it } from "vitest";
 import type { ChannelApprovalNativeAdapter } from "../channels/plugins/types.adapters.js";
 import { resolveChannelNativeApprovalDeliveryPlan } from "./approval-native-delivery.js";

src/infra/approval-request-filters.ts

@@ -1,3 +1,4 @@
+// Filters approval requests by agent and session patterns.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { parseAgentSessionKey } from "../routing/session-key.js";
 import { compileSafeRegex, testRegexWithBoundedInput } from "../security/safe-regex.js";

src/infra/command-carriers.ts

@@ -1,3 +1,4 @@
+// Identifies wrapper commands that can carry hidden command payloads.
 import { splitShellArgs } from "../utils/shell-argv.js";
 import { normalizeExecutableToken } from "./exec-wrapper-tokens.js";
 import { parseInlineOptionToken } from "./inline-option-token.js";

src/infra/dedupe.ts

@@ -1,3 +1,4 @@
+// Provides small process-local dedupe caches.
 import { resolveGlobalSingleton } from "../shared/global-singleton.js";
 import { pruneMapToMaxSize } from "./map-size.js";
 import { resolveNonNegativeIntegerOption } from "./numeric-options.js";

src/infra/disk-space.test.ts

@@ -1,3 +1,4 @@
+// Covers disk-space formatting and warning generation.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/infra/exec-safe-bin-policy.test.ts

@@ -1,3 +1,4 @@
+// Covers safe-bin policy profiles, validation, and generated docs text.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";

src/infra/exec-wrapper-tokens.ts

@@ -1,3 +1,4 @@
+// Normalizes executable tokens used by wrapper and policy analysis.
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 

src/infra/gateway-process-argv.ts

@@ -1,3 +1,4 @@
+// Parses gateway process command lines for process discovery.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 

src/infra/heartbeat-events-filter.test.ts

@@ -1,3 +1,4 @@
+// Covers heartbeat event prompt filtering.
 import { describe, expect, it } from "vitest";
 import {
   buildCronEventPrompt,

src/infra/heartbeat-visibility.ts

@@ -1,3 +1,4 @@
+// Resolves heartbeat visibility toggles across config precedence levels.
 import type { ChannelHeartbeatVisibilityConfig } from "../config/types.channels.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { GatewayMessageChannel } from "../utils/message-channel.js";

src/infra/install-source-utils.test.ts

@@ -1,3 +1,4 @@
+// Covers npm install source packing and archive path resolution.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

src/infra/map-size.test.ts

@@ -1,3 +1,4 @@
+// Covers bounded map pruning.
 import { describe, expect, it } from "vitest";
 import { pruneMapToMaxSize } from "./map-size.js";
 

src/infra/node-pairing-authz.ts

@@ -1,3 +1,4 @@
+// Maps node pairing command declarations to required operator scopes.
 import { NODE_SYSTEM_RUN_COMMANDS } from "./node-commands.js";
 
 /** Operator scopes required to approve a pending node pairing surface. */

src/infra/package-json.ts

@@ -1,3 +1,4 @@
+// Reads package.json metadata needed by install and update flows.
 import path from "node:path";
 import { normalizeNullableString as normalizeString } from "@openclaw/normalization-core/string-coerce";
 import { tryReadJson } from "./json-files.js";

src/infra/path-env.ts

@@ -1,3 +1,4 @@
+// Builds PATH values for OpenClaw child processes.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/infra/plugin-approvals.ts

@@ -1,3 +1,4 @@
+// Defines plugin approval request/resolution payloads and actions.
 import type { ExecApprovalDecision } from "./exec-approvals.js";
 
 // Plugin approval types and renderers mirror exec approval decisions while

src/infra/plugin-install-path-warnings.test.ts

@@ -1,3 +1,4 @@
+// Covers plugin install path warning detection and copy.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { withTempHome } from "openclaw/plugin-sdk/test-env";

src/infra/provider-usage.fetch.codex.test.ts

@@ -1,3 +1,4 @@
+// Covers Codex provider usage fetch parsing.
 import { describe, expect, it } from "vitest";
 import { createProviderUsageFetch, makeResponse } from "../test-utils/provider-usage-fetch.js";
 import { fetchCodexUsage } from "./provider-usage.fetch.codex.js";

src/infra/provider-usage.load.test.ts

@@ -1,3 +1,4 @@
+// Covers provider usage summary loading across auth and plugin paths.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createProviderUsageFetch, makeResponse } from "../test-utils/provider-usage-fetch.js";
 import {

src/infra/restart-stale-pids.test.ts

@@ -1,3 +1,4 @@
+// Covers stale gateway process detection and cleanup.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 // This file primarily tests lsof-based Unix port polling. On Windows,

src/infra/scp-host.ts

@@ -1,3 +1,4 @@
+// Normalizes SCP remote host and path values.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 // SCP host/path normalization rejects shell metacharacters before values are

src/infra/shell-inline-command.test.ts

@@ -1,3 +1,4 @@
+// Covers shell inline command flag parsing.
 import { describe, expect, it } from "vitest";
 import {
   POSIX_INLINE_COMMAND_FLAGS,

src/infra/system-run-normalize.test.ts

@@ -1,3 +1,4 @@
+// Covers system-run metadata normalization helpers.
 import { describe, expect, it } from "vitest";
 import { normalizeNonEmptyString, normalizeStringArray } from "./system-run-normalize.js";