docs: document infra event helpers

src/infra/channel-activity.ts

@@ -1,3 +1,4 @@
+// Tracks last inbound/outbound activity for channel accounts.
 import type { ChannelId } from "../channels/plugins/channel-id.types.js";
 
 /** Direction of the last observed activity for a channel/account pair. */

src/infra/event-session-routing.ts

@@ -1,3 +1,4 @@
+// Resolves event-triggered work to the correct session key and target.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { SessionScope } from "../config/types.base.js";

src/infra/exec-approval-channel-runtime.types.ts

@@ -1,3 +1,4 @@
+// Defines channel-native approval runtime contracts.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ExecApprovalRequest, ExecApprovalResolved } from "./exec-approvals.js";
 import type { PluginApprovalRequest, PluginApprovalResolved } from "./plugin-approvals.js";

src/infra/exec-approval-session-target.ts

@@ -1,3 +1,4 @@
+// Resolves approval delivery targets from sessions and turn sources.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveSessionConversationRef } from "../channels/plugins/session-conversation.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/infra/exec-safe-bin-trust.ts

@@ -1,3 +1,4 @@
+// Resolves trusted directories for safe-bin allowlist policy.
 import fs from "node:fs";
 import path from "node:path";
 import {

src/infra/fatal-error-hooks.test.ts

@@ -1,3 +1,4 @@
+// Covers fatal error hook registration and output collection.
 import { beforeEach, describe, expect, it } from "vitest";
 import {
   registerFatalErrorHook,

src/infra/git-commit.test.ts

@@ -1,3 +1,4 @@
+// Covers git commit helper behavior in fake repositories.
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";

src/infra/git-root.ts

@@ -1,3 +1,4 @@
+// Discovers git repository roots by walking ancestor directories.
 import fs from "node:fs";
 import path from "node:path";
 

src/infra/heartbeat-runner.commitments.test.ts

@@ -1,3 +1,4 @@
+// Covers heartbeat commitment checks and runner scheduling behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";

src/infra/heartbeat-runner.isolated-key-stability.test.ts

@@ -1,3 +1,4 @@
+// Covers heartbeat system-event isolation by stable session keys.
 import fs from "node:fs/promises";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import * as replyModule from "../auto-reply/reply.js";

src/infra/heartbeat-runner.model-override.test.ts

@@ -1,3 +1,4 @@
+// Covers heartbeat model override routing.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveAgentMainSessionKey, resolveMainSessionKey } from "../config/sessions.js";

src/infra/heartbeat-typing.test.ts

@@ -1,3 +1,4 @@
+// Covers heartbeat typing callback cadence and gating.
 import { describe, expect, it, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.public.js";
 import type { OpenClawConfig } from "../config/config.js";

src/infra/heartbeat-wake.ts

@@ -1,3 +1,4 @@
+// Tracks heartbeat wake requests, busy skips, and retry timing.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveTimerTimeoutMs } from "../shared/number-coercion.js";
 import { normalizeHeartbeatWakeReason } from "./heartbeat-reason.js";

src/infra/inline-option-token.test.ts

@@ -1,3 +1,4 @@
+// Covers inline CLI option token parsing.
 import { describe, expect, it } from "vitest";
 import { parseInlineOptionToken } from "./inline-option-token.js";
 

src/infra/machine-name.test.ts

@@ -1,3 +1,4 @@
+// Covers machine name resolution fallback behavior.
 import os from "node:os";
 import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";
 import { afterEach, describe, expect, it, vi } from "vitest";

src/infra/node-sqlite.ts

@@ -1,3 +1,4 @@
+// Loads node:sqlite with OpenClaw warning handling.
 import { createRequire } from "node:module";
 import { formatErrorMessage } from "./errors.js";
 import { installProcessWarningFilter } from "./warning-filter.js";

src/infra/package-tag.ts

@@ -1,3 +1,4 @@
+// Normalizes package tag inputs for install/update flows.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Normalizes a package tag input, stripping known package-name prefixes when present. */

src/infra/ports.test.ts

@@ -1,3 +1,4 @@
+// Covers gateway port availability and diagnostics behavior.
 import net from "node:net";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { stripAnsi } from "../../packages/terminal-core/src/ansi.js";

src/infra/ports.ts

@@ -1,3 +1,4 @@
+// Checks gateway port usage and reports listener diagnostics.
 import { danger, info, shouldLogVerbose, warn } from "../globals.js";
 import { logDebug } from "../logger.js";
 import type { RuntimeEnv } from "../runtime.js";

src/infra/private-file-store.ts

@@ -1,3 +1,4 @@
+// Creates private fs-safe file stores.
 import "./fs-safe-defaults.js";
 import {
   fileStore,

src/infra/provider-usage.auth.normalizes-keys.test.ts

@@ -1,3 +1,4 @@
+// Covers provider usage auth profile key normalization.
 import nodeFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";

src/infra/remote-env.ts

@@ -1,3 +1,4 @@
+// Detects remote/container environments where local desktop UX is unavailable.
 import { isWSLEnv } from "./wsl.js";
 
 // Remote environment detection gates local UX that depends on a desktop session

src/infra/sibling-temp-file.ts

@@ -1,3 +1,4 @@
+// Exposes sibling temp file writes with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Atomic sibling temp writes preserve target-directory permissions and avoid

src/infra/system-events.test.ts

@@ -1,3 +1,4 @@
+// Covers system event queue routing, draining, and formatting.
 import { beforeEach, describe, expect, it } from "vitest";
 import { drainFormattedSystemEvents } from "../auto-reply/reply/session-system-events.js";
 import type { OpenClawConfig } from "../config/config.js";