docs: document infra pairing helpers

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

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.

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

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

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

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

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

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 {

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

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,

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 {

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

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

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 {

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

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

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

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,

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

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

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

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

src/infra/system-run-command.ts

@@ -1,3 +1,4 @@
+// Normalizes and validates system-run commands before approval binding.
 import {
   extractShellWrapperCommand,
   hasEnvManipulationBeforeShellWrapper,

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,