From 87d053c0cb134db7f3de08556cfe21ee3c4380a4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 20:02:33 -0400
Subject: [PATCH] docs: document shared helpers

---
 src/shared/agent-run-status.test.ts                    | 1 +
 src/shared/assistant-error-format.ts                   | 1 +
 src/shared/assistant-identity-values.test.ts           | 1 +
 src/shared/assistant-identity-values.ts                | 1 +
 src/shared/avatar-policy.test.ts                       | 1 +
 src/shared/avatar-policy.ts                            | 1 +
 src/shared/chat-content.test.ts                        | 1 +
 src/shared/chat-envelope.test.ts                       | 1 +
 src/shared/chat-envelope.ts                            | 1 +
 src/shared/chat-message-content.test.ts                | 1 +
 src/shared/chat-message-content.ts                     | 1 +
 src/shared/config-eval.test.ts                         | 1 +
 src/shared/config-eval.ts                              | 1 +
 src/shared/custom-command-config.ts                    | 1 +
 src/shared/device-auth-store.test.ts                   | 1 +
 src/shared/device-auth-store.ts                        | 1 +
 src/shared/device-auth.test.ts                         | 1 +
 src/shared/device-bootstrap-profile.test.ts            | 1 +
 src/shared/device-bootstrap-profile.ts                 | 1 +
 src/shared/device-pairing-access.test.ts               | 1 +
 src/shared/device-pairing-access.ts                    | 1 +
 src/shared/entry-metadata.test.ts                      | 1 +
 src/shared/entry-metadata.ts                           | 1 +
 src/shared/entry-status.test.ts                        | 1 +
 src/shared/entry-status.ts                             | 1 +
 src/shared/frontmatter.test.ts                         | 1 +
 src/shared/frontmatter.ts                              | 1 +
 src/shared/gateway-bind-url.test.ts                    | 1 +
 src/shared/gateway-bind-url.ts                         | 1 +
 src/shared/gateway-method-policy.ts                    | 1 +
 src/shared/gateway-tailscale-auth-policy.ts            | 1 +
 src/shared/global-singleton.test.ts                    | 1 +
 src/shared/google-models.ts                            | 1 +
 src/shared/google-turn-ordering.ts                     | 1 +
 src/shared/import-specifier.ts                         | 1 +
 src/shared/json-schema-defaults.ts                     | 1 +
 src/shared/json-schema.types.ts                        | 1 +
 src/shared/lazy-promise.test.ts                        | 1 +
 src/shared/lazy-runtime.ts                             | 1 +
 src/shared/model-param-b.test.ts                       | 1 +
 src/shared/model-param-b.ts                            | 1 +
 src/shared/node-list-parse.test.ts                     | 1 +
 src/shared/node-list-parse.ts                          | 1 +
 src/shared/node-match.test.ts                          | 1 +
 src/shared/node-match.ts                               | 1 +
 src/shared/node-presence.ts                            | 1 +
 src/shared/node-resolve.test.ts                        | 1 +
 src/shared/node-resolve.ts                             | 1 +
 src/shared/operator-scope-compat.test.ts               | 1 +
 src/shared/operator-scope-compat.ts                    | 1 +
 src/shared/pid-alive.test.ts                           | 1 +
 src/shared/pid-alive.ts                                | 1 +
 src/shared/requirements.test.ts                        | 1 +
 src/shared/requirements.ts                             | 1 +
 src/shared/runtime-import.test.ts                      | 1 +
 src/shared/scoped-expiring-id-cache.test.ts            | 1 +
 src/shared/silent-reply-policy.test.ts                 | 1 +
 src/shared/silent-reply-policy.ts                      | 1 +
 src/shared/string-sample.test.ts                       | 1 +
 src/shared/subagents-format.test.ts                    | 1 +
 src/shared/subagents-format.ts                         | 1 +
 src/shared/tailscale-status.test.ts                    | 1 +
 src/shared/tailscale-status.ts                         | 1 +
 src/shared/text-chunking.test.ts                       | 1 +
 src/shared/text/assistant-visible-text.test.ts         | 1 +
 src/shared/text/assistant-visible-text.ts              | 1 +
 src/shared/text/auto-linked-file-ref.ts                | 1 +
 src/shared/text/citation-control-markers.test.ts       | 1 +
 src/shared/text/citation-control-markers.ts            | 1 +
 src/shared/text/code-regions.test.ts                   | 1 +
 src/shared/text/code-regions.ts                        | 1 +
 src/shared/text/final-tags.ts                          | 1 +
 src/shared/text/formatted-reasoning-message.ts         | 1 +
 src/shared/text/join-segments.test.ts                  | 1 +
 src/shared/text/model-special-tokens.ts                | 1 +
 src/shared/text/reasoning-tag-text-partitioner.test.ts | 1 +
 src/shared/text/reasoning-tag-text-partitioner.ts      | 1 +
 src/shared/text/reasoning-tags.test.ts                 | 1 +
 src/shared/text/reasoning-tags.ts                      | 1 +
 src/shared/text/tool-call-shaped-text.test.ts          | 1 +
 src/shared/text/tool-call-shaped-text.ts               | 1 +
 src/shared/thread-binding-lifecycle.test.ts            | 1 +
 src/shared/usage-aggregates.test.ts                    | 1 +
 src/shared/usage-aggregates.ts                         | 1 +
 src/shared/usage-types.ts                              | 1 +
 85 files changed, 85 insertions(+)

diff --git a/src/shared/agent-run-status.test.ts b/src/shared/agent-run-status.test.ts
index b4d70c633663..af883d9924f2 100644
--- a/src/shared/agent-run-status.test.ts
+++ b/src/shared/agent-run-status.test.ts
@@ -1,3 +1,4 @@
+// Agent run status tests cover status normalization for agent run records.
 import { describe, expect, it } from "vitest";
 import { isNonTerminalAgentRunStatus } from "./agent-run-status.js";
 
diff --git a/src/shared/assistant-error-format.ts b/src/shared/assistant-error-format.ts
index a618dd2a9984..a2a35f1df9c1 100644
--- a/src/shared/assistant-error-format.ts
+++ b/src/shared/assistant-error-format.ts
@@ -1,3 +1,4 @@
+// Assistant error formatting helpers normalize assistant-visible error payloads.
 const ERROR_PAYLOAD_PREFIX_RE =
   /^(?:error|(?:[a-z][\w-]*\s+)?api\s*error|apierror|openai\s*error|anthropic\s*error|gateway\s*error|codex\s*error)(?:\s+\d{3})?[:\s-]+/i;
 const HTTP_STATUS_DELIMITER_RE = /(?:\s*:\s*|\s+)/;
diff --git a/src/shared/assistant-identity-values.test.ts b/src/shared/assistant-identity-values.test.ts
index ef3440ee2a0c..82a7fb20e6f8 100644
--- a/src/shared/assistant-identity-values.test.ts
+++ b/src/shared/assistant-identity-values.test.ts
@@ -1,3 +1,4 @@
+// Assistant identity tests cover normalized assistant names and metadata values.
 import { describe, expect, it } from "vitest";
 import { coerceIdentityValue } from "./assistant-identity-values.js";
 
diff --git a/src/shared/assistant-identity-values.ts b/src/shared/assistant-identity-values.ts
index 5dba17c26e2d..8a9de4c6b33a 100644
--- a/src/shared/assistant-identity-values.ts
+++ b/src/shared/assistant-identity-values.ts
@@ -1,3 +1,4 @@
+// Assistant identity helpers normalize assistant identity labels and metadata.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Normalizes optional assistant identity fields and truncates them to the caller's limit. */
diff --git a/src/shared/avatar-policy.test.ts b/src/shared/avatar-policy.test.ts
index 9f2dadeca0cb..5edce4708897 100644
--- a/src/shared/avatar-policy.test.ts
+++ b/src/shared/avatar-policy.test.ts
@@ -1,3 +1,4 @@
+// Avatar policy tests cover avatar source resolution and fallback behavior.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/src/shared/avatar-policy.ts b/src/shared/avatar-policy.ts
index 316a366ba933..81c60e2f55bd 100644
--- a/src/shared/avatar-policy.ts
+++ b/src/shared/avatar-policy.ts
@@ -1,3 +1,4 @@
+// Avatar policy helpers resolve avatar paths and provider fallback rules.
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { isPathInside } from "../infra/path-guards.js";
diff --git a/src/shared/chat-content.test.ts b/src/shared/chat-content.test.ts
index e6e72aa1c8ff..e7b7527feca9 100644
--- a/src/shared/chat-content.test.ts
+++ b/src/shared/chat-content.test.ts
@@ -1,3 +1,4 @@
+// Chat content tests cover message content normalization for chat surfaces.
 import { describe, expect, it } from "vitest";
 import { extractTextFromChatContent } from "./chat-content.js";
 
diff --git a/src/shared/chat-envelope.test.ts b/src/shared/chat-envelope.test.ts
index ca214f37316b..fd4c0b2f1e9b 100644
--- a/src/shared/chat-envelope.test.ts
+++ b/src/shared/chat-envelope.test.ts
@@ -1,3 +1,4 @@
+// Chat envelope tests cover parsing and formatting channel-prefixed chat text.
 import { describe, expect, it } from "vitest";
 import { stripEnvelope, stripMessageIdHints } from "./chat-envelope.js";
 
diff --git a/src/shared/chat-envelope.ts b/src/shared/chat-envelope.ts
index 1ead5fb4789d..7959759a5043 100644
--- a/src/shared/chat-envelope.ts
+++ b/src/shared/chat-envelope.ts
@@ -1,3 +1,4 @@
+// Chat envelope helpers parse and format channel prefixes in chat text.
 const ENVELOPE_PREFIX = /^\[([^\]]+)\]\s*/;
 const ENVELOPE_CHANNELS = [
   "WebChat",
diff --git a/src/shared/chat-message-content.test.ts b/src/shared/chat-message-content.test.ts
index f04fb7419875..d3498f3ea33d 100644
--- a/src/shared/chat-message-content.test.ts
+++ b/src/shared/chat-message-content.test.ts
@@ -1,3 +1,4 @@
+// Chat message content tests cover visible text extraction from message parts.
 import { describe, expect, it } from "vitest";
 import {
   extractAssistantTextForPhase,
diff --git a/src/shared/chat-message-content.ts b/src/shared/chat-message-content.ts
index 0124e4f928c7..bbeee09e67b1 100644
--- a/src/shared/chat-message-content.ts
+++ b/src/shared/chat-message-content.ts
@@ -1,3 +1,4 @@
+// Chat message content helpers extract user-visible text from mixed message parts.
 import { readStringValue } from "@openclaw/normalization-core/string-coerce";
 
 /** Returns inline string content or the first array text block without scanning later blocks. */
diff --git a/src/shared/config-eval.test.ts b/src/shared/config-eval.test.ts
index 9175cd1daea3..429d6f2b6825 100644
--- a/src/shared/config-eval.test.ts
+++ b/src/shared/config-eval.test.ts
@@ -1,3 +1,4 @@
+// Config eval tests cover dynamic config loading and evaluation guards.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/shared/config-eval.ts b/src/shared/config-eval.ts
index afcc10347d2d..8ef064cf8337 100644
--- a/src/shared/config-eval.ts
+++ b/src/shared/config-eval.ts
@@ -1,3 +1,4 @@
+// Config evaluation helpers load dynamic config modules with guarded evaluation.
 import fs from "node:fs";
 import path from "node:path";
 
diff --git a/src/shared/custom-command-config.ts b/src/shared/custom-command-config.ts
index 880aaa687a87..8d962f43120c 100644
--- a/src/shared/custom-command-config.ts
+++ b/src/shared/custom-command-config.ts
@@ -1,3 +1,4 @@
+// Custom command config helpers normalize command configuration records.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Raw custom slash-command entry from config. */
diff --git a/src/shared/device-auth-store.test.ts b/src/shared/device-auth-store.test.ts
index 6213ed01362c..842f5d22b688 100644
--- a/src/shared/device-auth-store.test.ts
+++ b/src/shared/device-auth-store.test.ts
@@ -1,3 +1,4 @@
+// Device auth store tests cover persisted paired-device auth state.
 import { describe, expect, it, vi } from "vitest";
 import {
   clearDeviceAuthTokenFromStore,
diff --git a/src/shared/device-auth-store.ts b/src/shared/device-auth-store.ts
index 0c7d5a5971de..5a29a95cf2c4 100644
--- a/src/shared/device-auth-store.ts
+++ b/src/shared/device-auth-store.ts
@@ -1,3 +1,4 @@
+// Device auth store helpers persist and normalize paired device auth records.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   type DeviceAuthEntry,
diff --git a/src/shared/device-auth.test.ts b/src/shared/device-auth.test.ts
index 57450df8d983..167e5576dc59 100644
--- a/src/shared/device-auth.test.ts
+++ b/src/shared/device-auth.test.ts
@@ -1,3 +1,4 @@
+// Device auth tests cover role and scope normalization for paired devices.
 import { describe, expect, it } from "vitest";
 import { normalizeDeviceAuthRole, normalizeDeviceAuthScopes } from "./device-auth.js";
 
diff --git a/src/shared/device-bootstrap-profile.test.ts b/src/shared/device-bootstrap-profile.test.ts
index 3c3397756e9b..728349c28634 100644
--- a/src/shared/device-bootstrap-profile.test.ts
+++ b/src/shared/device-bootstrap-profile.test.ts
@@ -1,3 +1,4 @@
+// Device bootstrap profile tests cover profile normalization for paired devices.
 import { describe, expect, test } from "vitest";
 import {
   BOOTSTRAP_HANDOFF_OPERATOR_SCOPES,
diff --git a/src/shared/device-bootstrap-profile.ts b/src/shared/device-bootstrap-profile.ts
index a0e2abdb9206..a491824dea24 100644
--- a/src/shared/device-bootstrap-profile.ts
+++ b/src/shared/device-bootstrap-profile.ts
@@ -1,3 +1,4 @@
+// Device bootstrap profile helpers build profile claims for device onboarding.
 import { normalizeDeviceAuthRole, normalizeDeviceAuthScopes } from "./device-auth.js";
 
 /** Normalized roles/scopes carried by a bootstrap token during device handoff. */
diff --git a/src/shared/device-pairing-access.test.ts b/src/shared/device-pairing-access.test.ts
index fe2ef41a1496..c5aeb0c281a9 100644
--- a/src/shared/device-pairing-access.test.ts
+++ b/src/shared/device-pairing-access.test.ts
@@ -1,3 +1,4 @@
+// Device pairing access tests cover role and scope checks for pairing requests.
 import { describe, expect, it } from "vitest";
 import { resolvePendingDeviceApprovalState } from "./device-pairing-access.js";
 
diff --git a/src/shared/device-pairing-access.ts b/src/shared/device-pairing-access.ts
index fb1cc5de8a66..bedf6af63a9e 100644
--- a/src/shared/device-pairing-access.ts
+++ b/src/shared/device-pairing-access.ts
@@ -1,3 +1,4 @@
+// Device pairing access helpers evaluate pairing scopes and role permissions.
 import { normalizeDeviceAuthScopes } from "./device-auth.js";
 
 export type DevicePairingAccessSummary = {
diff --git a/src/shared/entry-metadata.test.ts b/src/shared/entry-metadata.test.ts
index eb7c176b1836..aa8aefc06320 100644
--- a/src/shared/entry-metadata.test.ts
+++ b/src/shared/entry-metadata.test.ts
@@ -1,3 +1,4 @@
+// Entry metadata tests cover display metadata resolution for agents and jobs.
 import { describe, expect, it } from "vitest";
 import { resolveEmojiAndHomepage } from "./entry-metadata.js";
 
diff --git a/src/shared/entry-metadata.ts b/src/shared/entry-metadata.ts
index 5e8cbb182586..476e0f45aba8 100644
--- a/src/shared/entry-metadata.ts
+++ b/src/shared/entry-metadata.ts
@@ -1,3 +1,4 @@
+// Entry metadata helpers resolve display names, emojis, and homepage links.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Resolves entry emoji/homepage with metadata taking precedence over frontmatter aliases. */
diff --git a/src/shared/entry-status.test.ts b/src/shared/entry-status.test.ts
index da493db0a50d..1b816188e7d8 100644
--- a/src/shared/entry-status.test.ts
+++ b/src/shared/entry-status.test.ts
@@ -1,3 +1,4 @@
+// Entry status tests cover normalized status labels and terminal-state behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { mockProcessPlatform } from "../test-utils/vitest-spies.js";
 import {
diff --git a/src/shared/entry-status.ts b/src/shared/entry-status.ts
index 9a583ee7c1f1..f59a594f993e 100644
--- a/src/shared/entry-status.ts
+++ b/src/shared/entry-status.ts
@@ -1,3 +1,4 @@
+// Entry status helpers resolve display metadata for run and queue entries.
 import { resolveEmojiAndHomepage } from "./entry-metadata.js";
 import {
   evaluateRequirementsFromMetadataWithRemote,
diff --git a/src/shared/frontmatter.test.ts b/src/shared/frontmatter.test.ts
index e4aed1c31604..3c47823a99d0 100644
--- a/src/shared/frontmatter.test.ts
+++ b/src/shared/frontmatter.test.ts
@@ -1,3 +1,4 @@
+// Frontmatter tests cover shared Markdown frontmatter parsing helpers.
 import { describe, expect, it, test } from "vitest";
 import {
   applyOpenClawManifestInstallCommonFields,
diff --git a/src/shared/frontmatter.ts b/src/shared/frontmatter.ts
index 92cd582bf11b..b5f912caa96d 100644
--- a/src/shared/frontmatter.ts
+++ b/src/shared/frontmatter.ts
@@ -1,3 +1,4 @@
+// Shared frontmatter helpers parse Markdown frontmatter blocks and body text.
 import {
   normalizeOptionalLowercaseString,
   readStringValue,
diff --git a/src/shared/gateway-bind-url.test.ts b/src/shared/gateway-bind-url.test.ts
index 5bf9c8582a5b..f6c4c2606e13 100644
--- a/src/shared/gateway-bind-url.test.ts
+++ b/src/shared/gateway-bind-url.test.ts
@@ -1,3 +1,4 @@
+// Gateway bind URL tests cover host and port normalization for gateway listeners.
 import { describe, expect, it, vi } from "vitest";
 import { resolveGatewayBindUrl } from "./gateway-bind-url.js";
 
diff --git a/src/shared/gateway-bind-url.ts b/src/shared/gateway-bind-url.ts
index 62f32f286abc..5e8d65e80129 100644
--- a/src/shared/gateway-bind-url.ts
+++ b/src/shared/gateway-bind-url.ts
@@ -1,3 +1,4 @@
+// Gateway bind URL helpers compute listener URLs from host and port settings.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 export type GatewayBindUrlResult =
diff --git a/src/shared/gateway-method-policy.ts b/src/shared/gateway-method-policy.ts
index 5d9fb602b7c6..32242dd71296 100644
--- a/src/shared/gateway-method-policy.ts
+++ b/src/shared/gateway-method-policy.ts
@@ -1,3 +1,4 @@
+// Gateway method policy helpers classify reserved and operator-only gateway methods.
 const RESERVED_ADMIN_GATEWAY_METHOD_PREFIXES = [
   "exec.approvals.",
   "config.",
diff --git a/src/shared/gateway-tailscale-auth-policy.ts b/src/shared/gateway-tailscale-auth-policy.ts
index e1f222f53a39..9af96e4cc95a 100644
--- a/src/shared/gateway-tailscale-auth-policy.ts
+++ b/src/shared/gateway-tailscale-auth-policy.ts
@@ -1,3 +1,4 @@
+// Gateway Tailscale auth policy helpers describe auth requirements for Tailscale modes.
 import type { GatewayAuthMode, GatewayTailscaleMode } from "../config/types.gateway.js";
 
 /** True when Tailscale exposure is configured without gateway authentication. */
diff --git a/src/shared/global-singleton.test.ts b/src/shared/global-singleton.test.ts
index 34b4e8817f38..4613d8833a08 100644
--- a/src/shared/global-singleton.test.ts
+++ b/src/shared/global-singleton.test.ts
@@ -1,3 +1,4 @@
+// Global singleton tests cover process-wide singleton creation and reset behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveGlobalMap, resolveGlobalSingleton } from "./global-singleton.js";
 
diff --git a/src/shared/google-models.ts b/src/shared/google-models.ts
index ca46a2aeaf34..d192501777ed 100644
--- a/src/shared/google-models.ts
+++ b/src/shared/google-models.ts
@@ -1,3 +1,4 @@
+// Google model helpers normalize Google model identifiers and aliases.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Return true when a model id/name refers to the Gemma 4 family. */
diff --git a/src/shared/google-turn-ordering.ts b/src/shared/google-turn-ordering.ts
index 5a1f71aa2a50..129dcfb0a608 100644
--- a/src/shared/google-turn-ordering.ts
+++ b/src/shared/google-turn-ordering.ts
@@ -1,3 +1,4 @@
+// Google turn ordering helpers keep Google model conversations in supported order.
 import type { AgentMessage } from "../agents/runtime/index.js";
 
 const GOOGLE_TURN_ORDER_BOOTSTRAP_TEXT = "(session bootstrap)";
diff --git a/src/shared/import-specifier.ts b/src/shared/import-specifier.ts
index ceed20819d28..e4cd431c3577 100644
--- a/src/shared/import-specifier.ts
+++ b/src/shared/import-specifier.ts
@@ -1,3 +1,4 @@
+// Import specifier helpers convert paths to stable ESM import specifiers.
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
diff --git a/src/shared/json-schema-defaults.ts b/src/shared/json-schema-defaults.ts
index c4222e26386d..6a4b018eb03a 100644
--- a/src/shared/json-schema-defaults.ts
+++ b/src/shared/json-schema-defaults.ts
@@ -1,3 +1,4 @@
+// JSON schema default helpers fill object values from TypeBox schema defaults.
 import { Compile } from "typebox/compile";
 import type { JsonSchemaObject } from "./json-schema.types.js";
 import { parseConfigPathArrayIndex } from "./path-array-index.js";
diff --git a/src/shared/json-schema.types.ts b/src/shared/json-schema.types.ts
index ad940e366196..b96322bf93bb 100644
--- a/src/shared/json-schema.types.ts
+++ b/src/shared/json-schema.types.ts
@@ -1,3 +1,4 @@
+// JSON schema shared types keep TypeBox schema aliases consistent across callers.
 import type { TSchema } from "typebox";
 
 /** TypeBox schema value widened for generic JSON-schema object transforms. */
diff --git a/src/shared/lazy-promise.test.ts b/src/shared/lazy-promise.test.ts
index 120ab07dd565..dbacd78ac0c0 100644
--- a/src/shared/lazy-promise.test.ts
+++ b/src/shared/lazy-promise.test.ts
@@ -1,3 +1,4 @@
+// Lazy promise tests cover single-flight loading and error reuse behavior.
 import { describe, expect, it, vi } from "vitest";
 import { createLazyImportLoader, createLazyPromiseLoader } from "./lazy-promise.js";
 
diff --git a/src/shared/lazy-runtime.ts b/src/shared/lazy-runtime.ts
index 23f6a6039dec..e84ec3094ccc 100644
--- a/src/shared/lazy-runtime.ts
+++ b/src/shared/lazy-runtime.ts
@@ -1,3 +1,4 @@
+// Lazy runtime helpers expose dynamic imports through cached runtime surfaces.
 export function createLazyRuntimeSurface<TModule, TSurface>(
   importer: () => Promise<TModule>,
   select: (module: TModule) => TSurface,
diff --git a/src/shared/model-param-b.test.ts b/src/shared/model-param-b.test.ts
index 8bbafe3f529a..5359f3bc39d7 100644
--- a/src/shared/model-param-b.test.ts
+++ b/src/shared/model-param-b.test.ts
@@ -1,3 +1,4 @@
+// Model parameter B tests cover reasoning budget normalization and aliases.
 import { describe, expect, it } from "vitest";
 import { inferParamBFromIdOrName } from "./model-param-b.js";
 
diff --git a/src/shared/model-param-b.ts b/src/shared/model-param-b.ts
index cdb425c5529d..6c564ee5d4fc 100644
--- a/src/shared/model-param-b.ts
+++ b/src/shared/model-param-b.ts
@@ -1,3 +1,4 @@
+// Model parameter B helpers normalize provider-specific reasoning budget values.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Infers the largest `<number>b` parameter-size token from a model id or display name. */
diff --git a/src/shared/node-list-parse.test.ts b/src/shared/node-list-parse.test.ts
index 27c8bca20ff3..3713221484fb 100644
--- a/src/shared/node-list-parse.test.ts
+++ b/src/shared/node-list-parse.test.ts
@@ -1,3 +1,4 @@
+// Node list parsing tests cover normalized node inventory records.
 import { describe, expect, it } from "vitest";
 import { parseNodeList, parsePairingList } from "./node-list-parse.js";
 
diff --git a/src/shared/node-list-parse.ts b/src/shared/node-list-parse.ts
index f748de8aa797..862068077a44 100644
--- a/src/shared/node-list-parse.ts
+++ b/src/shared/node-list-parse.ts
@@ -1,3 +1,4 @@
+// Node list parsing helpers normalize node inventory records from CLI output.
 import { asRecord } from "@openclaw/normalization-core/record-coerce";
 import type { NodeListNode, PairedNode, PairingList, PendingRequest } from "./node-list-types.js";
 
diff --git a/src/shared/node-match.test.ts b/src/shared/node-match.test.ts
index 5fa6103483c2..60c17cae538a 100644
--- a/src/shared/node-match.test.ts
+++ b/src/shared/node-match.test.ts
@@ -1,3 +1,4 @@
+// Node match tests cover node selection from names, ids, and address hints.
 import { describe, expect, it } from "vitest";
 import { normalizeNodeKey, resolveNodeIdFromCandidates, resolveNodeMatches } from "./node-match.js";
 
diff --git a/src/shared/node-match.ts b/src/shared/node-match.ts
index 46a72d819836..21adbd1fa8ab 100644
--- a/src/shared/node-match.ts
+++ b/src/shared/node-match.ts
@@ -1,3 +1,4 @@
+// Node match helpers score and select nodes from names, ids, and addresses.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
diff --git a/src/shared/node-presence.ts b/src/shared/node-presence.ts
index 2d21f9c3e9ba..a9d4f4ec5045 100644
--- a/src/shared/node-presence.ts
+++ b/src/shared/node-presence.ts
@@ -1,3 +1,4 @@
+// Node presence helpers normalize live node presence and heartbeat metadata.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Gateway event name used by node hosts to refresh their last-seen presence. */
diff --git a/src/shared/node-resolve.test.ts b/src/shared/node-resolve.test.ts
index 2020073a910d..af300072abfe 100644
--- a/src/shared/node-resolve.test.ts
+++ b/src/shared/node-resolve.test.ts
@@ -1,3 +1,4 @@
+// Node resolve tests cover node identity and address resolution helpers.
 import { describe, expect, it } from "vitest";
 import { resolveNodeFromNodeList, resolveNodeIdFromNodeList } from "./node-resolve.js";
 
diff --git a/src/shared/node-resolve.ts b/src/shared/node-resolve.ts
index fd609d9d90d4..215146d3e8e3 100644
--- a/src/shared/node-resolve.ts
+++ b/src/shared/node-resolve.ts
@@ -1,3 +1,4 @@
+// Node resolution helpers resolve node references from names, ids, and URLs.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { type NodeMatchCandidate, resolveNodeIdFromCandidates } from "./node-match.js";
 
diff --git a/src/shared/operator-scope-compat.test.ts b/src/shared/operator-scope-compat.test.ts
index c6f2feea5dbc..ce873cd9fb81 100644
--- a/src/shared/operator-scope-compat.test.ts
+++ b/src/shared/operator-scope-compat.test.ts
@@ -1,3 +1,4 @@
+// Operator scope compatibility tests cover legacy operator scope normalization.
 import { describe, expect, it } from "vitest";
 import {
   resolveMissingRequestedScope,
diff --git a/src/shared/operator-scope-compat.ts b/src/shared/operator-scope-compat.ts
index 6ed805dd8f93..7933942d64be 100644
--- a/src/shared/operator-scope-compat.ts
+++ b/src/shared/operator-scope-compat.ts
@@ -1,3 +1,4 @@
+// Operator scope compatibility helpers normalize legacy operator role names.
 const OPERATOR_ROLE = "operator";
 const OPERATOR_ADMIN_SCOPE = "operator.admin";
 const OPERATOR_READ_SCOPE = "operator.read";
diff --git a/src/shared/pid-alive.test.ts b/src/shared/pid-alive.test.ts
index 75fc248d7dfb..16b58eccd397 100644
--- a/src/shared/pid-alive.test.ts
+++ b/src/shared/pid-alive.test.ts
@@ -1,3 +1,4 @@
+// PID liveness tests cover process existence checks across platforms.
 import fsSync from "node:fs";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withMockedPlatform } from "../test-utils/vitest-spies.js";
diff --git a/src/shared/pid-alive.ts b/src/shared/pid-alive.ts
index 456256f9acb1..55016872fa35 100644
--- a/src/shared/pid-alive.ts
+++ b/src/shared/pid-alive.ts
@@ -1,3 +1,4 @@
+// PID liveness helpers check whether process ids still refer to active processes.
 import fsSync from "node:fs";
 
 function isValidPid(pid: number): boolean {
diff --git a/src/shared/requirements.test.ts b/src/shared/requirements.test.ts
index 874480208018..7e2f9cb24de8 100644
--- a/src/shared/requirements.test.ts
+++ b/src/shared/requirements.test.ts
@@ -1,3 +1,4 @@
+// Requirement tests cover merging and formatting runtime requirements.
 import { describe, expect, it } from "vitest";
 import {
   buildConfigChecks,
diff --git a/src/shared/requirements.ts b/src/shared/requirements.ts
index 14c75e44e710..8e5b0ce91d6b 100644
--- a/src/shared/requirements.ts
+++ b/src/shared/requirements.ts
@@ -1,3 +1,4 @@
+// Requirement types describe runtime requirements advertised by shared surfaces.
 export type Requirements = {
   bins: string[];
   anyBins: string[];
diff --git a/src/shared/runtime-import.test.ts b/src/shared/runtime-import.test.ts
index 16e195910831..6a15041e9082 100644
--- a/src/shared/runtime-import.test.ts
+++ b/src/shared/runtime-import.test.ts
@@ -1,3 +1,4 @@
+// Runtime import tests cover lazy runtime import caching and failure handling.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   importRuntimeModule,
diff --git a/src/shared/scoped-expiring-id-cache.test.ts b/src/shared/scoped-expiring-id-cache.test.ts
index abb177b59e1b..57de9da227e2 100644
--- a/src/shared/scoped-expiring-id-cache.test.ts
+++ b/src/shared/scoped-expiring-id-cache.test.ts
@@ -1,3 +1,4 @@
+// Scoped expiring id cache tests cover TTL and scope isolation behavior.
 import { describe, expect, it } from "vitest";
 import { createScopedExpiringIdCache } from "./scoped-expiring-id-cache.js";
 
diff --git a/src/shared/silent-reply-policy.test.ts b/src/shared/silent-reply-policy.test.ts
index 3fea5467eb2b..c756a3e14f83 100644
--- a/src/shared/silent-reply-policy.test.ts
+++ b/src/shared/silent-reply-policy.test.ts
@@ -1,3 +1,4 @@
+// Silent reply policy tests cover reply suppression decision rules.
 import { describe, expect, it } from "vitest";
 import {
   DEFAULT_SILENT_REPLY_POLICY,
diff --git a/src/shared/silent-reply-policy.ts b/src/shared/silent-reply-policy.ts
index b773e256aae2..fc0b1a69a6be 100644
--- a/src/shared/silent-reply-policy.ts
+++ b/src/shared/silent-reply-policy.ts
@@ -1,3 +1,4 @@
+// Silent reply policy helpers decide when automated replies should be suppressed.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 export type SilentReplyPolicy = "allow" | "disallow";
diff --git a/src/shared/string-sample.test.ts b/src/shared/string-sample.test.ts
index 783a6499fcd4..152dd2aa3993 100644
--- a/src/shared/string-sample.test.ts
+++ b/src/shared/string-sample.test.ts
@@ -1,3 +1,4 @@
+// String sample tests cover compact string sampling and truncation behavior.
 import { describe, expect, it } from "vitest";
 import { summarizeStringEntries } from "./string-sample.js";
 
diff --git a/src/shared/subagents-format.test.ts b/src/shared/subagents-format.test.ts
index be424a648524..8663bfd94621 100644
--- a/src/shared/subagents-format.test.ts
+++ b/src/shared/subagents-format.test.ts
@@ -1,3 +1,4 @@
+// Subagent format tests cover concise subagent status and duration formatting.
 import { describe, expect, it } from "vitest";
 import {
   formatDurationCompact,
diff --git a/src/shared/subagents-format.ts b/src/shared/subagents-format.ts
index f681b81fa629..e1c202321baf 100644
--- a/src/shared/subagents-format.ts
+++ b/src/shared/subagents-format.ts
@@ -1,3 +1,4 @@
+// Subagent formatting helpers expose compact durations and status text.
 export { formatDurationCompact } from "../infra/format-time/format-duration.ts";
 
 /** Formats token counts using compact k/m suffixes for subagent summaries. */
diff --git a/src/shared/tailscale-status.test.ts b/src/shared/tailscale-status.test.ts
index ebd89629a4c1..67012cd8d172 100644
--- a/src/shared/tailscale-status.test.ts
+++ b/src/shared/tailscale-status.test.ts
@@ -1,3 +1,4 @@
+// Tailscale status tests cover status parsing and validation.
 import { describe, expect, it, vi } from "vitest";
 import { resolveTailnetHostWithRunner } from "./tailscale-status.js";
 
diff --git a/src/shared/tailscale-status.ts b/src/shared/tailscale-status.ts
index a3c55cd59358..49abea50767f 100644
--- a/src/shared/tailscale-status.ts
+++ b/src/shared/tailscale-status.ts
@@ -1,3 +1,4 @@
+// Tailscale status helpers parse and validate status payloads from Tailscale.
 import { z } from "zod";
 import { safeParseJsonWithSchema } from "../utils/zod-parse.js";
 
diff --git a/src/shared/text-chunking.test.ts b/src/shared/text-chunking.test.ts
index 433e8c75df99..051a08c17024 100644
--- a/src/shared/text-chunking.test.ts
+++ b/src/shared/text-chunking.test.ts
@@ -1,3 +1,4 @@
+// Text chunking tests cover splitting text into bounded model-safe chunks.
 import { describe, expect, it } from "vitest";
 import { chunkTextByBreakResolver } from "./text-chunking.js";
 
diff --git a/src/shared/text/assistant-visible-text.test.ts b/src/shared/text/assistant-visible-text.test.ts
index b84cd4588a64..4a86b2f36a84 100644
--- a/src/shared/text/assistant-visible-text.test.ts
+++ b/src/shared/text/assistant-visible-text.test.ts
@@ -1,3 +1,4 @@
+// Assistant visible text tests cover extracting user-visible assistant output.
 import { describe, expect, it } from "vitest";
 import {
   sanitizeAssistantVisibleText,
diff --git a/src/shared/text/assistant-visible-text.ts b/src/shared/text/assistant-visible-text.ts
index 8a09e4391d57..39eab9a6a5d3 100644
--- a/src/shared/text/assistant-visible-text.ts
+++ b/src/shared/text/assistant-visible-text.ts
@@ -1,3 +1,4 @@
+// Assistant visible text helpers strip hidden reasoning and control marker text.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 import { stripModelSpecialTokens } from "./model-special-tokens.js";
diff --git a/src/shared/text/auto-linked-file-ref.ts b/src/shared/text/auto-linked-file-ref.ts
index bb5d494d4621..5a7423650b39 100644
--- a/src/shared/text/auto-linked-file-ref.ts
+++ b/src/shared/text/auto-linked-file-ref.ts
@@ -1,3 +1,4 @@
+// Auto-linked file ref helpers detect file references that can be linked in UI text.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 const FILE_REF_EXTENSIONS = ["md", "go", "py", "pl", "sh", "am", "at", "be", "cc"] as const;
diff --git a/src/shared/text/citation-control-markers.test.ts b/src/shared/text/citation-control-markers.test.ts
index 788fe4510866..d9567ab26e4d 100644
--- a/src/shared/text/citation-control-markers.test.ts
+++ b/src/shared/text/citation-control-markers.test.ts
@@ -1,3 +1,4 @@
+// Citation control marker tests cover stripping unsupported citation markers.
 import { describe, expect, it } from "vitest";
 import { stripUnsupportedCitationControlMarkers } from "./citation-control-markers.js";
 
diff --git a/src/shared/text/citation-control-markers.ts b/src/shared/text/citation-control-markers.ts
index c0622de01402..812af316cdc8 100644
--- a/src/shared/text/citation-control-markers.ts
+++ b/src/shared/text/citation-control-markers.ts
@@ -1,3 +1,4 @@
+// Citation control marker helpers remove unsupported citation control tokens.
 const UNSUPPORTED_CITATION_CONTROL_MARKER_RE = /cite(?:[^]*)?/g;
 const TRAILING_UNSUPPORTED_CITATION_CONTROL_MARKER_RE = /[ \t]*cite(?:[^]*)?(?=\r?\n|$)/g;
 
diff --git a/src/shared/text/code-regions.test.ts b/src/shared/text/code-regions.test.ts
index d726883d66ab..4331985efd01 100644
--- a/src/shared/text/code-regions.test.ts
+++ b/src/shared/text/code-regions.test.ts
@@ -1,3 +1,4 @@
+// Code region tests cover Markdown code span and fence detection.
 import { describe, expect, it } from "vitest";
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 
diff --git a/src/shared/text/code-regions.ts b/src/shared/text/code-regions.ts
index 4576088306b0..ad99b2044ff8 100644
--- a/src/shared/text/code-regions.ts
+++ b/src/shared/text/code-regions.ts
@@ -1,3 +1,4 @@
+// Code region helpers find fenced and inline code spans in Markdown text.
 export interface CodeRegion {
   start: number;
   end: number;
diff --git a/src/shared/text/final-tags.ts b/src/shared/text/final-tags.ts
index 5b42e1865d0c..8c93210b9d54 100644
--- a/src/shared/text/final-tags.ts
+++ b/src/shared/text/final-tags.ts
@@ -1,3 +1,4 @@
+// Final tag helpers detect final-answer tag regions in assistant text.
 export type FinalTagMatch = {
   index: number;
   text: string;
diff --git a/src/shared/text/formatted-reasoning-message.ts b/src/shared/text/formatted-reasoning-message.ts
index 822f37b70c7a..c5ba4992d50c 100644
--- a/src/shared/text/formatted-reasoning-message.ts
+++ b/src/shared/text/formatted-reasoning-message.ts
@@ -1,3 +1,4 @@
+// Formatted reasoning message helpers remove reasoning tags before display.
 import { stripReasoningTagsFromText } from "./reasoning-tags.js";
 
 /** Strip provider-formatted Reasoning/Thinking preambles from visible text. */
diff --git a/src/shared/text/join-segments.test.ts b/src/shared/text/join-segments.test.ts
index 95c629d93951..c66d0056289e 100644
--- a/src/shared/text/join-segments.test.ts
+++ b/src/shared/text/join-segments.test.ts
@@ -1,3 +1,4 @@
+// Join segment tests cover stable text segment recombination.
 import { describe, expect, it } from "vitest";
 import { concatOptionalTextSegments, joinPresentTextSegments } from "./join-segments.js";
 
diff --git a/src/shared/text/model-special-tokens.ts b/src/shared/text/model-special-tokens.ts
index 710fe0a1a704..8ffd5bf2929c 100644
--- a/src/shared/text/model-special-tokens.ts
+++ b/src/shared/text/model-special-tokens.ts
@@ -1,3 +1,4 @@
+// Model special token helpers strip model control tokens outside code regions.
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 
 // Match both ASCII pipe <|...|> and full-width pipe <｜...｜> (U+FF5C) variants.
diff --git a/src/shared/text/reasoning-tag-text-partitioner.test.ts b/src/shared/text/reasoning-tag-text-partitioner.test.ts
index 2da263503a5b..9644f4eaa8cb 100644
--- a/src/shared/text/reasoning-tag-text-partitioner.test.ts
+++ b/src/shared/text/reasoning-tag-text-partitioner.test.ts
@@ -1,3 +1,4 @@
+// Reasoning tag partitioner tests cover splitting reasoning and visible text segments.
 import { describe, expect, it } from "vitest";
 import { createReasoningTagTextPartitioner } from "./reasoning-tag-text-partitioner.js";
 
diff --git a/src/shared/text/reasoning-tag-text-partitioner.ts b/src/shared/text/reasoning-tag-text-partitioner.ts
index b3e14f335666..c3e441599f15 100644
--- a/src/shared/text/reasoning-tag-text-partitioner.ts
+++ b/src/shared/text/reasoning-tag-text-partitioner.ts
@@ -1,3 +1,4 @@
+// Reasoning tag partitioner helpers split text around reasoning tag regions.
 import {
   buildCodeSpanIndex,
   createInlineCodeState,
diff --git a/src/shared/text/reasoning-tags.test.ts b/src/shared/text/reasoning-tags.test.ts
index e92d2cde2f7c..034a70a8c974 100644
--- a/src/shared/text/reasoning-tags.test.ts
+++ b/src/shared/text/reasoning-tags.test.ts
@@ -1,3 +1,4 @@
+// Reasoning tag tests cover parsing and stripping reasoning tag blocks.
 import { describe, expect, it } from "vitest";
 import { stripReasoningTagsFromText } from "./reasoning-tags.js";
 
diff --git a/src/shared/text/reasoning-tags.ts b/src/shared/text/reasoning-tags.ts
index 4de9d119eb0f..9f3318a21460 100644
--- a/src/shared/text/reasoning-tags.ts
+++ b/src/shared/text/reasoning-tags.ts
@@ -1,3 +1,4 @@
+// Reasoning tag helpers find and remove model reasoning tag blocks from text.
 import { findCodeRegions, isInsideCode } from "./code-regions.js";
 import { findFinalTagMatches } from "./final-tags.js";
 export type ReasoningTagMode = "strict" | "preserve";
diff --git a/src/shared/text/tool-call-shaped-text.test.ts b/src/shared/text/tool-call-shaped-text.test.ts
index 025603bfbb62..e10ea5231559 100644
--- a/src/shared/text/tool-call-shaped-text.test.ts
+++ b/src/shared/text/tool-call-shaped-text.test.ts
@@ -1,3 +1,4 @@
+// Tool-call shaped text tests cover detection of text that resembles tool calls.
 import { describe, expect, it } from "vitest";
 import { detectToolCallShapedText } from "./tool-call-shaped-text.js";
 
diff --git a/src/shared/text/tool-call-shaped-text.ts b/src/shared/text/tool-call-shaped-text.ts
index d8bd5650e324..263f0970c541 100644
--- a/src/shared/text/tool-call-shaped-text.ts
+++ b/src/shared/text/tool-call-shaped-text.ts
@@ -1,3 +1,4 @@
+// Tool-call shaped text helpers detect malformed text that resembles tool calls.
 import { asOptionalRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString as readTrimmedString } from "@openclaw/normalization-core/string-coerce";
 
diff --git a/src/shared/thread-binding-lifecycle.test.ts b/src/shared/thread-binding-lifecycle.test.ts
index b5bc56b9fb80..7b5003294b28 100644
--- a/src/shared/thread-binding-lifecycle.test.ts
+++ b/src/shared/thread-binding-lifecycle.test.ts
@@ -1,3 +1,4 @@
+// Thread binding lifecycle tests cover binding states across channel threads.
 import { describe, expect, it } from "vitest";
 import { resolveThreadBindingLifecycle } from "./thread-binding-lifecycle.js";
 
diff --git a/src/shared/usage-aggregates.test.ts b/src/shared/usage-aggregates.test.ts
index 3ab9af2a19b2..7c4525397c44 100644
--- a/src/shared/usage-aggregates.test.ts
+++ b/src/shared/usage-aggregates.test.ts
@@ -1,3 +1,4 @@
+// Usage aggregate tests cover token, cost, and latency accumulation.
 import { describe, expect, it } from "vitest";
 import {
   buildUsageAggregateTail,
diff --git a/src/shared/usage-aggregates.ts b/src/shared/usage-aggregates.ts
index 68ed7925fd38..774866604407 100644
--- a/src/shared/usage-aggregates.ts
+++ b/src/shared/usage-aggregates.ts
@@ -1,3 +1,4 @@
+// Usage aggregate helpers accumulate token, cost, and latency usage totals.
 type LatencyTotalsLike = {
   count: number;
   sum: number;
diff --git a/src/shared/usage-types.ts b/src/shared/usage-types.ts
index e90c36fd5a3e..d125b943c4d7 100644
--- a/src/shared/usage-types.ts
+++ b/src/shared/usage-types.ts
@@ -1,3 +1,4 @@
+// Usage types define shared usage accounting structures for sessions and runs.
 import type { SessionSystemPromptReport } from "../config/sessions/types.js";
 import type {
   CostUsageSummary,