docs: document daemon service env helpers

steipete · steipete · commit 407f4777d2e8 · 2026-06-04T13:58:33.000-04:00
diff --git a/src/daemon/service-env.ts b/src/daemon/service-env.ts
@@ -1,3 +1,4 @@
+/** Builds minimal, portable environment blocks for managed daemon services. */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -65,6 +66,8 @@ export const SERVICE_PROXY_ENV_KEYS = [
 function readServiceProxyEnvironment(
   env: Record<string, string | undefined>,
 ): Record<string, string | undefined> {
+  // Service env intentionally preserves only the canonical OpenClaw proxy knob;
+  // generic shell proxy vars are audited but not frozen into services.
   const proxyUrl = normalizeOptionalString(env.OPENCLAW_PROXY_URL);
   return proxyUrl ? { OPENCLAW_PROXY_URL: proxyUrl } : {};
 }
@@ -90,6 +93,8 @@ function realpathServicePathDir(dir: string): string | undefined {
 function realpathExistingServicePathDir(dir: string): string | undefined {
   const parts: string[] = [];
   let current = dir;
+  // Resolve the nearest existing ancestor so future-created bin dirs can still
+  // be compared against the install workspace realpath.
   while (current && current !== path.posix.dirname(current)) {
     const realCurrent = realpathServicePathDir(current);
     if (realCurrent) {
@@ -333,6 +338,8 @@ function resolveLinuxUserBinDirs(
 export function getMinimalServicePathParts(options: MinimalServicePathOptions = {}): string[] {
   const platform = options.platform ?? process.platform;
   if (platform === "win32") {
+    // Windows scheduled tasks inherit PATH from the task host; generated cmd
+    // launchers should not freeze install-time PATH snapshots.
     return [];
   }
 
diff --git a/src/daemon/service-layout.ts b/src/daemon/service-layout.ts
@@ -1,3 +1,4 @@
+/** Summarizes installed service command paths and OpenClaw package layout. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../infra/fs-safe.js";
@@ -81,6 +82,8 @@ async function isSourceCheckoutRoot(candidate: string): Promise<boolean> {
 
 async function resolveOpenClawPackageRoot(entrypoint: string): Promise<string | undefined> {
   let current = path.dirname(path.resolve(entrypoint));
+  // Installed dist entrypoints can sit several levels below package root in
+  // pnpm layouts; bound the walk to avoid scanning arbitrary filesystem depth.
   for (let depth = 0; depth < 8; depth += 1) {
     const packageJson = path.join(current, "package.json");
     if (await pathExists(packageJson)) {
diff --git a/src/daemon/service-managed-env.ts b/src/daemon/service-managed-env.ts
@@ -1,3 +1,4 @@
+/** Tracks managed service environment keys across reinstall and repair flows. */
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { normalizeEnvVarKey } from "../infra/host-env-security.js";
 import type { GatewayServiceEnvironmentValueSource } from "./service-types.js";
@@ -92,6 +93,8 @@ function deleteManagedServiceEnvKeys(
   if (normalizedKeys.size === 0) {
     return;
   }
+  // Delete by normalized key so casing changes between installs do not leave
+  // stale service-owned values behind.
   for (const rawKey of Object.keys(environment)) {
     const key = normalizeServiceEnvKey(rawKey);
     if (key && normalizedKeys.has(key)) {
@@ -155,6 +158,8 @@ export function collectInlineManagedServiceEnvKeys(
     if (!hasInlineEnvironmentSource(readEnvironmentValueSource(command, normalized))) {
       continue;
     }
+    // Only inline/file-overlap sources can be repaired from the service command
+    // itself; file-only values must stay owned by the generated env file.
     inlineKeys.push(normalized);
   }
   return sortUniqueStrings(inlineKeys);
diff --git a/src/daemon/service-path-policy.ts b/src/daemon/service-path-policy.ts
@@ -1,3 +1,4 @@
+/** Classifies service PATH entries that should not be frozen into daemons. */
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
@@ -20,6 +21,8 @@ export function isNonMinimalServicePathEntry(entry: string, platform: NodeJS.Pla
     return false;
   }
   const normalized = normalizeServicePathEntry(entry, platform);
+  // User shell package-manager paths are fragile in non-interactive services and
+  // should be replaced by stable system/runtime paths.
   return (
     normalized.includes("/.nvm/") ||
     normalized.includes("/.fnm/") ||
diff --git a/src/daemon/service-runtime.ts b/src/daemon/service-runtime.ts
@@ -1,3 +1,4 @@
+/** Shared daemon runtime status types and systemd cgroup hygiene helpers. */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** systemd cgroup fields used to spot unhealthy gateway service supervision. */
@@ -46,6 +47,7 @@ function describeSystemdCgroupLoadWarnings(runtime?: GatewayServiceSystemdRuntim
   if (!isRiskySystemdKillMode(killMode)) {
     return [];
   }
+  // KillMode=process/none only becomes noisy when the cgroup is visibly large.
   const details: string[] = [];
   if (
     runtime.tasksCurrent !== undefined &&
diff --git a/src/daemon/service-types.ts b/src/daemon/service-types.ts
@@ -1,3 +1,4 @@
+/** Shared daemon service argument, state, and command config contracts. */
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 
 /** Environment map passed to service renderers and platform supervisors. */
@@ -35,6 +36,7 @@ export type GatewayServiceEnvArgs = {
 
 export type GatewayServiceEnvironmentValueSource = "inline" | "file" | "inline-and-file";
 
+/** Parsed command and env metadata from an installed platform service. */
 export type GatewayServiceCommandConfig = {
   programArguments: string[];
   workingDirectory?: string;
