docs: document launchd daemon helpers

steipete · steipete · commit 975d40d47483 · 2026-06-04T13:54:21.000-04:00
diff --git a/src/daemon/gateway-entrypoint.ts b/src/daemon/gateway-entrypoint.ts
@@ -1,3 +1,4 @@
+/** Resolves gateway dist entrypoints used by installed daemon command lines. */
 import path from "node:path";
 import { pathExists } from "../utils.js";
 
@@ -36,6 +37,8 @@ export function buildGatewayDistEntrypointCandidates(...inputs: string[]): strin
     distDirs.push(distDir);
   }
 
+  // Prefer canonical basenames across every observed dist dir before falling
+  // through, so repaired services converge on the same entrypoint order.
   const candidates: string[] = [];
   for (const basename of GATEWAY_DIST_ENTRYPOINT_BASENAMES) {
     for (const distDir of distDirs) {
diff --git a/src/daemon/inspect.ts b/src/daemon/inspect.ts
@@ -1,3 +1,4 @@
+/** Inspects installed platform services for extra OpenClaw or legacy gateway jobs. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
@@ -75,7 +76,8 @@ function hasGatewaySubcommandArg(args: string[]): boolean {
 }
 
 export function detectMarkerLineWithGateway(contents: string): Marker | null {
-  // Join line continuations (trailing backslash) into single lines
+  // Join line continuations before scanning systemd ExecStart commands; marker
+  // detection must ignore relationship-only unit keys.
   const lower = normalizeLowercaseStringOrEmpty(contents.replace(/\\\r?\n\s*/g, " "));
   for (const line of lower.split(/\r?\n/)) {
     const trimmed = line.trim();
@@ -163,6 +165,8 @@ function detectLaunchdGatewayExecutionMarker(contents: string): Marker | null {
   if (!hasGatewaySubcommandArg(programArguments)) {
     return null;
   }
+  // Only execution command fields identify gateway jobs; labels alone catch too
+  // many unrelated helper jobs.
   const launchCommand = normalizeLowercaseStringOrEmpty(
     [...program, ...programArguments].filter(Boolean).join("\n"),
   );
@@ -296,6 +300,8 @@ async function scanLaunchdDir(params: {
     if (!marker) {
       continue;
     }
+    // Managed current services are expected; this scan reports extra jobs that
+    // can compete for ports or survive old installs.
     if (isIgnoredLaunchdLabel(label)) {
       continue;
     }
diff --git a/src/daemon/launchd-current-service.ts b/src/daemon/launchd-current-service.ts
@@ -1,3 +1,4 @@
+/** Detects whether the current process is running inside a launchd service label. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 export type CurrentProcessLaunchdServiceLabelOptions = {
@@ -31,6 +32,8 @@ export function isCurrentProcessLaunchdServiceLabel(
     normalizeOptionalString(env.OPENCLAW_SERVICE_MARKER) === "openclaw" &&
     Boolean(normalizeOptionalString(env.OPENCLAW_SERVICE_KIND))
   ) {
+    // Managed wrappers inject service metadata; trust it when launchd's own
+    // label variables are absent or renamed by the host environment.
     return true;
   }
   return options.allowConfiguredLabelFallback !== false && currentLabels.length === 0;
diff --git a/src/daemon/launchd-plist.ts b/src/daemon/launchd-plist.ts
@@ -1,3 +1,4 @@
+/** Reads and renders macOS LaunchAgent plists for gateway service installs. */
 import fs from "node:fs/promises";
 import type { GatewayServiceEnvironmentValueSource } from "./service-types.js";
 
@@ -119,6 +120,8 @@ async function readLaunchAgentEnvironmentFile(
       ].filter((candidate): candidate is string => Boolean(candidate)),
     ),
   );
+  // Corrupted wrapper args can still point near the generated env dir. Try the
+  // sibling canonical env file before giving up so repair rewrites retain env.
   for (const candidate of candidateEnvFilePaths) {
     try {
       content = await fs.readFile(candidate, "utf8");
@@ -237,6 +240,8 @@ export async function readLaunchAgentProgramArgumentsFromFile(
     const effectiveProgramArguments = unwrapGeneratedEnvWrapperArgs(args, options);
     const environment = { ...inlineEnvironment, ...fileEnvironment };
     const environmentValueSources: Record<string, GatewayServiceEnvironmentValueSource> = {};
+    // Track source provenance so repair flows can tell inline plist env from the
+    // generated env file and preserve both when they overlap.
     for (const key of Object.keys(inlineEnvironment)) {
       environmentValueSources[key] = Object.hasOwn(fileEnvironment, key)
         ? "inline-and-file"
diff --git a/src/daemon/launchd-restart-handoff.ts b/src/daemon/launchd-restart-handoff.ts
@@ -1,3 +1,4 @@
+/** Detached macOS launchd restart handoff for restarting from inside the service. */
 import { spawn } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
@@ -97,6 +98,8 @@ function buildLaunchdRestartScript(
   mode: LaunchdRestartHandoffMode,
   restartLogEnv: LaunchdRestartLogEnv,
 ): string {
+  // The detached shell waits for the caller before touching launchd so the
+  // current gateway process can exit cleanly after scheduling the handoff.
   const waitForCallerPid = `wait_pid="$4"
 label="$5"
 ${renderPosixRestartLogSetup(restartLogEnv)}
diff --git a/src/daemon/launchd.ts b/src/daemon/launchd.ts
@@ -1,3 +1,4 @@
+/** macOS LaunchAgent installer, runtime inspection, and lifecycle controls. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
@@ -61,6 +62,8 @@ function normalizeOpenClawUpdateLaunchdLabel(label: unknown): string | null {
   if (trimmed.startsWith(OPENCLAW_UPDATE_LAUNCHD_LABEL_PREFIX)) {
     return trimmed;
   }
+  // Manual update jobs include a timestamp-like suffix and should be cleaned up
+  // without matching arbitrary ai.openclaw labels.
   return OPENCLAW_MANUAL_UPDATE_LAUNCHD_LABEL_PATTERN.test(trimmed) ? trimmed : null;
 }
 
@@ -200,6 +203,8 @@ async function prepareLaunchAgentProgramArguments(params: {
     return { programArguments: params.programArguments };
   }
 
+  // Environment values with secrets live in an owner-only env file instead of
+  // inline plist XML, which can be harder to rotate and audit.
   const envDir = resolveLaunchAgentEnvDir(params.env);
   const envFilePath = resolveLaunchAgentEnvFilePath(params.env, params.label);
   const wrapperPath = resolveLaunchAgentEnvWrapperPath(params.env, params.label);
@@ -327,6 +332,8 @@ export async function findStaleOpenClawUpdateLaunchdJobs(
   if (result.code !== 0) {
     return [];
   }
+  // Never report the active gateway label as stale even when a wrapper exposes
+  // update-like launchd metadata through the current environment.
   return parseLaunchctlListOpenClawUpdateJobs(result.stdout).filter(
     (job) => !isCurrentGatewayLaunchdLabel(job.label, env),
   );
