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

---
 src/infra/approval-errors.test.ts                          | 1 +
 src/infra/archive.ts                                       | 1 +
 src/infra/boundary-file-read.ts                            | 1 +
 src/infra/device-auth-store.test.ts                        | 1 +
 src/infra/device-identity.ts                               | 1 +
 src/infra/device-pairing.ts                                | 1 +
 src/infra/exec-approval-channel-runtime.ts                 | 1 +
 src/infra/exec-approvals-parity.test.ts                    | 1 +
 src/infra/exec-auto-review.test.ts                         | 1 +
 src/infra/heartbeat-cooldown.test.ts                       | 1 +
 src/infra/heartbeat-runner.skips-busy-session-lane.test.ts | 1 +
 src/infra/heartbeat-runner.tool-response.test.ts           | 1 +
 src/infra/heartbeat-visibility.test.ts                     | 1 +
 src/infra/network-interfaces.test.ts                       | 1 +
 src/infra/package-update-utils.ts                          | 1 +
 src/infra/pairing-files.ts                                 | 1 +
 src/infra/permissions.ts                                   | 1 +
 src/infra/provider-usage.auth.ts                           | 1 +
 src/infra/replace-file.ts                                  | 1 +
 src/infra/root-paths.ts                                    | 1 +
 src/infra/system-presence.test.ts                          | 1 +
 src/infra/system-run-approval-mismatch.contract.test.ts    | 1 +
 src/infra/system-run-command.ts                            | 1 +
 src/infra/unhandled-rejections.test.ts                     | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/infra/approval-errors.test.ts b/src/infra/approval-errors.test.ts
index 621409b5ba88..28681e1c3ee4 100644
--- a/src/infra/approval-errors.test.ts
+++ b/src/infra/approval-errors.test.ts
@@ -1,3 +1,4 @@
+// Covers approval-not-found error detection.
 import { describe, expect, it } from "vitest";
 import { isApprovalNotFoundError } from "./approval-errors.js";
 
diff --git a/src/infra/archive.ts b/src/infra/archive.ts
index 26d981a804bd..1a46e4693495 100644
--- a/src/infra/archive.ts
+++ b/src/infra/archive.ts
@@ -1,3 +1,4 @@
+// Exposes archive extraction helpers after applying fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Archive extraction facade for size limits, staged writes, and traversal checks.
diff --git a/src/infra/boundary-file-read.ts b/src/infra/boundary-file-read.ts
index 1460ee5b4ac0..dde34dbca8a0 100644
--- a/src/infra/boundary-file-read.ts
+++ b/src/infra/boundary-file-read.ts
@@ -1,3 +1,4 @@
+// Exposes root-scoped file open helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Root-scoped file open helpers. Use these for user paths that must stay under
diff --git a/src/infra/device-auth-store.test.ts b/src/infra/device-auth-store.test.ts
index 23c644c52204..9ccda7ecb61f 100644
--- a/src/infra/device-auth-store.test.ts
+++ b/src/infra/device-auth-store.test.ts
@@ -1,3 +1,4 @@
+// Covers persistent device auth token storage and clearing.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
diff --git a/src/infra/device-identity.ts b/src/infra/device-identity.ts
index 37faa23c145f..333f5237d5da 100644
--- a/src/infra/device-identity.ts
+++ b/src/infra/device-identity.ts
@@ -1,3 +1,4 @@
+// Stores and converts the gateway/device Ed25519 identity.
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/infra/device-pairing.ts b/src/infra/device-pairing.ts
index 266c9d6f024f..534061f47dc0 100644
--- a/src/infra/device-pairing.ts
+++ b/src/infra/device-pairing.ts
@@ -1,3 +1,4 @@
+// Manages device pairing requests, approvals, and token issuance.
 import { randomUUID } from "node:crypto";
 import { normalizeUniqueSingleOrTrimmedStringList } from "@openclaw/normalization-core/string-normalization";
 import { normalizeDeviceAuthScopes } from "../shared/device-auth.js";
diff --git a/src/infra/exec-approval-channel-runtime.ts b/src/infra/exec-approval-channel-runtime.ts
index 1d56ec3d43ed..e0b9b789a174 100644
--- a/src/infra/exec-approval-channel-runtime.ts
+++ b/src/infra/exec-approval-channel-runtime.ts
@@ -1,3 +1,4 @@
+// Runs the gateway-backed runtime that delivers native approval events.
 import { readConnectErrorDetailCode } from "../../packages/gateway-protocol/src/connect-error-details.js";
 import type { EventFrame } from "../../packages/gateway-protocol/src/index.js";
 import { startGatewayClientWhenEventLoopReady } from "../gateway/client-start-readiness.js";
diff --git a/src/infra/exec-approvals-parity.test.ts b/src/infra/exec-approvals-parity.test.ts
index 2756d7f160fc..0c622159b482 100644
--- a/src/infra/exec-approvals-parity.test.ts
+++ b/src/infra/exec-approvals-parity.test.ts
@@ -1,3 +1,4 @@
+// Covers shell parser and wrapper-resolution parity fixtures.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/src/infra/exec-auto-review.test.ts b/src/infra/exec-auto-review.test.ts
index ab2633508c7a..b05f35c38c75 100644
--- a/src/infra/exec-auto-review.test.ts
+++ b/src/infra/exec-auto-review.test.ts
@@ -1,3 +1,4 @@
+// Covers conservative default exec auto-review decisions.
 import { describe, expect, it } from "vitest";
 import { defaultExecAutoReviewer, type ExecAutoReviewInput } from "./exec-auto-review.js";
 
diff --git a/src/infra/heartbeat-cooldown.test.ts b/src/infra/heartbeat-cooldown.test.ts
index aac55d2980f5..d465c271cbb4 100644
--- a/src/infra/heartbeat-cooldown.test.ts
+++ b/src/infra/heartbeat-cooldown.test.ts
@@ -1,3 +1,4 @@
+// Covers heartbeat wake cooldown and flood-deferral decisions.
 import { describe, expect, it } from "vitest";
 import {
   DEFAULT_FLOOD_THRESHOLD,
diff --git a/src/infra/heartbeat-runner.skips-busy-session-lane.test.ts b/src/infra/heartbeat-runner.skips-busy-session-lane.test.ts
index b0ad1c60c836..d1067c0d22e4 100644
--- a/src/infra/heartbeat-runner.skips-busy-session-lane.test.ts
+++ b/src/infra/heartbeat-runner.skips-busy-session-lane.test.ts
@@ -1,3 +1,4 @@
+// Covers heartbeat skipping while session lanes or cron jobs are busy.
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveNestedAgentLaneForSession } from "../agents/lanes.js";
 import {
diff --git a/src/infra/heartbeat-runner.tool-response.test.ts b/src/infra/heartbeat-runner.tool-response.test.ts
index 64253f8569a6..727e049ef1df 100644
--- a/src/infra/heartbeat-runner.tool-response.test.ts
+++ b/src/infra/heartbeat-runner.tool-response.test.ts
@@ -1,3 +1,4 @@
+// Covers heartbeat tool-response handling and visible reply policy.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/infra/heartbeat-visibility.test.ts b/src/infra/heartbeat-visibility.test.ts
index 7350ffea9fe0..c7ecd915d246 100644
--- a/src/infra/heartbeat-visibility.test.ts
+++ b/src/infra/heartbeat-visibility.test.ts
@@ -1,3 +1,4 @@
+// Covers heartbeat visibility resolution across defaults and accounts.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveHeartbeatVisibility } from "./heartbeat-visibility.js";
diff --git a/src/infra/network-interfaces.test.ts b/src/infra/network-interfaces.test.ts
index 598be742c674..e167b0bdd4e4 100644
--- a/src/infra/network-interfaces.test.ts
+++ b/src/infra/network-interfaces.test.ts
@@ -1,3 +1,4 @@
+// Covers safe network interface enumeration and address selection.
 import { describe, expect, it } from "vitest";
 import { makeNetworkInterfacesSnapshot } from "../test-helpers/network-interfaces.js";
 import {
diff --git a/src/infra/package-update-utils.ts b/src/infra/package-update-utils.ts
index 1e4e8d783ecd..eab159111994 100644
--- a/src/infra/package-update-utils.ts
+++ b/src/infra/package-update-utils.ts
@@ -1,3 +1,4 @@
+// Inspects installed package metadata for update/install verification.
 import fsSync from "node:fs";
 import path from "node:path";
 import { readRootJsonObjectSync } from "@openclaw/fs-safe/json";
diff --git a/src/infra/pairing-files.ts b/src/infra/pairing-files.ts
index 84a4f450a132..fda9e8a3e260 100644
--- a/src/infra/pairing-files.ts
+++ b/src/infra/pairing-files.ts
@@ -1,3 +1,4 @@
+// Shared JSON state helpers for pairing namespaces.
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
 
diff --git a/src/infra/permissions.ts b/src/infra/permissions.ts
index a129eb74eba0..4f31122ca464 100644
--- a/src/infra/permissions.ts
+++ b/src/infra/permissions.ts
@@ -1,3 +1,4 @@
+// Exposes cross-platform permission inspection helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Permission inspection facades expose fs-safe POSIX and Windows ACL helpers
diff --git a/src/infra/provider-usage.auth.ts b/src/infra/provider-usage.auth.ts
index 71ed662ad585..42962d83eb33 100644
--- a/src/infra/provider-usage.auth.ts
+++ b/src/infra/provider-usage.auth.ts
@@ -1,3 +1,4 @@
+// Resolves provider usage auth tokens from profiles, plugins, and env.
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import {
   dedupeProfileIds,
diff --git a/src/infra/replace-file.ts b/src/infra/replace-file.ts
index 041b00f4cd87..bdce7c529a88 100644
--- a/src/infra/replace-file.ts
+++ b/src/infra/replace-file.ts
@@ -1,3 +1,4 @@
+// Wraps fs-safe atomic replacement and move helpers for OpenClaw install flows.
 import "./fs-safe-defaults.js";
 import fs from "node:fs/promises";
 import path from "node:path";
diff --git a/src/infra/root-paths.ts b/src/infra/root-paths.ts
index be1b677a3cac..c70cbe57f5ef 100644
--- a/src/infra/root-paths.ts
+++ b/src/infra/root-paths.ts
@@ -1,3 +1,4 @@
+// Exposes root-scoped path resolution helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Root path helpers resolve writable and existing paths without allowing
diff --git a/src/infra/system-presence.test.ts b/src/infra/system-presence.test.ts
index 163590d01a7f..50824bdbe80e 100644
--- a/src/infra/system-presence.test.ts
+++ b/src/infra/system-presence.test.ts
@@ -1,3 +1,4 @@
+// Covers in-memory system presence merging and expiry behavior.
 import { randomUUID } from "node:crypto";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { listSystemPresence, updateSystemPresence, upsertPresence } from "./system-presence.js";
diff --git a/src/infra/system-run-approval-mismatch.contract.test.ts b/src/infra/system-run-approval-mismatch.contract.test.ts
index 06f964bce918..4b214183a07e 100644
--- a/src/infra/system-run-approval-mismatch.contract.test.ts
+++ b/src/infra/system-run-approval-mismatch.contract.test.ts
@@ -1,3 +1,4 @@
+// Verifies serialized system-run approval mismatch contract fixtures.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/infra/system-run-command.ts b/src/infra/system-run-command.ts
index 7275bab7d2a4..9cf68cbcfddf 100644
--- a/src/infra/system-run-command.ts
+++ b/src/infra/system-run-command.ts
@@ -1,3 +1,4 @@
+// Normalizes and validates system-run commands before approval binding.
 import {
   extractShellWrapperCommand,
   hasEnvManipulationBeforeShellWrapper,
diff --git a/src/infra/unhandled-rejections.test.ts b/src/infra/unhandled-rejections.test.ts
index 3a04baec26b0..9c1bbb84b36f 100644
--- a/src/infra/unhandled-rejections.test.ts
+++ b/src/infra/unhandled-rejections.test.ts
@@ -1,3 +1,4 @@
+// Covers transient and benign unhandled rejection classifiers.
 import { describe, expect, it } from "vitest";
 import {
   isAbortError,