From a628a66e4d1ecb455487b85388a41fdcdeb56658 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 20:14:34 -0400
Subject: [PATCH] docs: document process helpers

---
 src/process/child-process-bridge.ts                   | 1 +
 src/process/command-queue.test.ts                     | 1 +
 src/process/command-queue.ts                          | 1 +
 src/process/exec.no-output-timer.test.ts              | 1 +
 src/process/exec.test.ts                              | 1 +
 src/process/exec.ts                                   | 1 +
 src/process/exec.windows.test.ts                      | 1 +
 src/process/kill-tree.test.ts                         | 1 +
 src/process/linux-oom-score.test.ts                   | 1 +
 src/process/linux-oom-score.ts                        | 1 +
 src/process/respawn-child-runner.ts                   | 1 +
 src/process/spawn-utils.test.ts                       | 1 +
 src/process/spawn-utils.ts                            | 1 +
 src/process/supervisor/adapters/child.test.ts         | 1 +
 src/process/supervisor/adapters/child.ts              | 1 +
 src/process/supervisor/adapters/pty.test.ts           | 1 +
 src/process/supervisor/adapters/pty.ts                | 1 +
 src/process/supervisor/adapters/test-support.ts       | 1 +
 src/process/supervisor/index.ts                       | 1 +
 src/process/supervisor/registry.test.ts               | 1 +
 src/process/supervisor/registry.ts                    | 1 +
 src/process/supervisor/supervisor-log.runtime.ts      | 1 +
 src/process/supervisor/supervisor.pty-command.test.ts | 1 +
 src/process/supervisor/supervisor.test.ts             | 1 +
 src/process/supervisor/supervisor.ts                  | 1 +
 src/process/supervisor/types.ts                       | 1 +
 src/process/windows-command.test.ts                   | 1 +
 src/process/windows-command.ts                        | 1 +
 28 files changed, 28 insertions(+)

diff --git a/src/process/child-process-bridge.ts b/src/process/child-process-bridge.ts
index 40be8813b809..6ce80cec1d9b 100644
--- a/src/process/child-process-bridge.ts
+++ b/src/process/child-process-bridge.ts
@@ -1,3 +1,4 @@
+// Child process bridge adapts child process events into typed lifecycle callbacks.
 import type { ChildProcess } from "node:child_process";
 import process from "node:process";
 
diff --git a/src/process/command-queue.test.ts b/src/process/command-queue.test.ts
index d7b7f59bb196..3d1a94e98580 100644
--- a/src/process/command-queue.test.ts
+++ b/src/process/command-queue.test.ts
@@ -1,3 +1,4 @@
+// Command queue tests cover bounded command execution and queue ordering.
 import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { CommandLane } from "./lanes.js";
diff --git a/src/process/command-queue.ts b/src/process/command-queue.ts
index a1ad13395bf8..7515d4efda84 100644
--- a/src/process/command-queue.ts
+++ b/src/process/command-queue.ts
@@ -1,3 +1,4 @@
+// Command queue serializes and limits process execution for shared command lanes.
 import {
   diagnosticLogger as diag,
   logLaneDequeue,
diff --git a/src/process/exec.no-output-timer.test.ts b/src/process/exec.no-output-timer.test.ts
index 00223609b152..c876d8a6373e 100644
--- a/src/process/exec.no-output-timer.test.ts
+++ b/src/process/exec.no-output-timer.test.ts
@@ -1,3 +1,4 @@
+// No-output timer tests cover idle command timeout and output reset behavior.
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/process/exec.test.ts b/src/process/exec.test.ts
index 0cc3e117e500..e41ce7758a36 100644
--- a/src/process/exec.test.ts
+++ b/src/process/exec.test.ts
@@ -1,3 +1,4 @@
+// Exec tests cover command execution, output capture, and cancellation behavior.
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import process from "node:process";
diff --git a/src/process/exec.ts b/src/process/exec.ts
index 90fb14fe6803..083fce10e0e0 100644
--- a/src/process/exec.ts
+++ b/src/process/exec.ts
@@ -1,3 +1,4 @@
+// Exec helpers run subprocesses with normalized output, timeout, and abort handling.
 import { execFile, spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/process/exec.windows.test.ts b/src/process/exec.windows.test.ts
index 3173c079f03b..795ec329c3f6 100644
--- a/src/process/exec.windows.test.ts
+++ b/src/process/exec.windows.test.ts
@@ -1,3 +1,4 @@
+// Windows exec tests cover command invocation behavior on Windows paths.
 import type { execFile as execFileType } from "node:child_process";
 import { EventEmitter } from "node:events";
 import fs from "node:fs";
diff --git a/src/process/kill-tree.test.ts b/src/process/kill-tree.test.ts
index f749ca8fdee3..57fbe6709d53 100644
--- a/src/process/kill-tree.test.ts
+++ b/src/process/kill-tree.test.ts
@@ -1,3 +1,4 @@
+// Kill tree tests cover process tree termination and platform-specific fallbacks.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { withMockedPlatform } from "../test-utils/vitest-spies.js";
 
diff --git a/src/process/linux-oom-score.test.ts b/src/process/linux-oom-score.test.ts
index 667a5df14aec..b948b796b4fe 100644
--- a/src/process/linux-oom-score.test.ts
+++ b/src/process/linux-oom-score.test.ts
@@ -1,3 +1,4 @@
+// Linux OOM score tests cover best-effort process OOM score adjustment.
 import { describe, expect, it } from "vitest";
 import {
   hardenedEnvForChildOomWrap,
diff --git a/src/process/linux-oom-score.ts b/src/process/linux-oom-score.ts
index 382f6e2720ea..97b23de293d2 100644
--- a/src/process/linux-oom-score.ts
+++ b/src/process/linux-oom-score.ts
@@ -1,3 +1,4 @@
+// Linux OOM score helpers adjust child process OOM priority when supported.
 import fs from "node:fs";
 
 /**
diff --git a/src/process/respawn-child-runner.ts b/src/process/respawn-child-runner.ts
index d488d6e9e771..b97009dfb31b 100644
--- a/src/process/respawn-child-runner.ts
+++ b/src/process/respawn-child-runner.ts
@@ -1,3 +1,4 @@
+// Respawn child runner restarts child processes after configured exits.
 import type { ChildProcess, spawn } from "node:child_process";
 import type { attachChildProcessBridge } from "./child-process-bridge.js";
 
diff --git a/src/process/spawn-utils.test.ts b/src/process/spawn-utils.test.ts
index db2b70a4ec28..da5fd77153fc 100644
--- a/src/process/spawn-utils.test.ts
+++ b/src/process/spawn-utils.test.ts
@@ -1,3 +1,4 @@
+// Spawn utility tests cover child process setup and stream handling helpers.
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
diff --git a/src/process/spawn-utils.ts b/src/process/spawn-utils.ts
index 0333a3a3715f..b7b6ea092849 100644
--- a/src/process/spawn-utils.ts
+++ b/src/process/spawn-utils.ts
@@ -1,3 +1,4 @@
+// Spawn utilities configure child processes and normalize spawned process handles.
 import type { ChildProcess, SpawnOptions } from "node:child_process";
 import { spawn } from "node:child_process";
 
diff --git a/src/process/supervisor/adapters/child.test.ts b/src/process/supervisor/adapters/child.test.ts
index 7c81c71b0b45..ddeb84f0cf30 100644
--- a/src/process/supervisor/adapters/child.test.ts
+++ b/src/process/supervisor/adapters/child.test.ts
@@ -1,3 +1,4 @@
+// Child adapter tests cover adapting child processes to supervisor runs.
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
diff --git a/src/process/supervisor/adapters/child.ts b/src/process/supervisor/adapters/child.ts
index 2c849cfd0913..f335cbf6cad0 100644
--- a/src/process/supervisor/adapters/child.ts
+++ b/src/process/supervisor/adapters/child.ts
@@ -1,3 +1,4 @@
+// Child process adapter wraps spawned child processes for the supervisor.
 import type { ChildProcessWithoutNullStreams, SpawnOptions } from "node:child_process";
 import { createWindowsOutputDecoder } from "../../../infra/windows-encoding.js";
 import { signalProcessTree } from "../../kill-tree.js";
diff --git a/src/process/supervisor/adapters/pty.test.ts b/src/process/supervisor/adapters/pty.test.ts
index 2a043597ba24..69bf74e71029 100644
--- a/src/process/supervisor/adapters/pty.test.ts
+++ b/src/process/supervisor/adapters/pty.test.ts
@@ -1,3 +1,4 @@
+// PTY adapter tests cover PTY lifecycle and termination behavior.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   expectRealExitWinsOverSigkillFallback,
diff --git a/src/process/supervisor/adapters/pty.ts b/src/process/supervisor/adapters/pty.ts
index 49bd07e10d38..8a610ccba599 100644
--- a/src/process/supervisor/adapters/pty.ts
+++ b/src/process/supervisor/adapters/pty.ts
@@ -1,3 +1,4 @@
+// PTY adapter wraps pseudo-terminal processes for the process supervisor.
 import { signalProcessTree } from "../../kill-tree.js";
 import { prepareOomScoreAdjustedSpawn } from "../../linux-oom-score.js";
 import type { ManagedRunStdin, SpawnProcessAdapter } from "../types.js";
diff --git a/src/process/supervisor/adapters/test-support.ts b/src/process/supervisor/adapters/test-support.ts
index a27376d2b24d..06dd19bf7edd 100644
--- a/src/process/supervisor/adapters/test-support.ts
+++ b/src/process/supervisor/adapters/test-support.ts
@@ -1,3 +1,4 @@
+// Supervisor adapter test support builds mock process handles for adapter tests.
 import { expect, vi } from "vitest";
 
 /**
diff --git a/src/process/supervisor/index.ts b/src/process/supervisor/index.ts
index b34dcaae3831..f80c75f577db 100644
--- a/src/process/supervisor/index.ts
+++ b/src/process/supervisor/index.ts
@@ -1,3 +1,4 @@
+// Process supervisor barrel exposes the supervised process API.
 import { createProcessSupervisor } from "./supervisor.js";
 import type { ProcessSupervisor } from "./types.js";
 
diff --git a/src/process/supervisor/registry.test.ts b/src/process/supervisor/registry.test.ts
index 472e2915fa57..80bb997157ca 100644
--- a/src/process/supervisor/registry.test.ts
+++ b/src/process/supervisor/registry.test.ts
@@ -1,3 +1,4 @@
+// Supervisor registry tests cover run registration, lookup, and pruning behavior.
 import { describe, expect, it } from "vitest";
 import { createRunRegistry } from "./registry.js";
 
diff --git a/src/process/supervisor/registry.ts b/src/process/supervisor/registry.ts
index 620655178347..32913aba0a29 100644
--- a/src/process/supervisor/registry.ts
+++ b/src/process/supervisor/registry.ts
@@ -1,3 +1,4 @@
+// Supervisor registry tracks active and historical supervised process runs.
 import type { RunRecord, RunState, TerminationReason } from "./types.js";
 
 /** In-memory run index for the supervisor; callers receive detached snapshots. */
diff --git a/src/process/supervisor/supervisor-log.runtime.ts b/src/process/supervisor/supervisor-log.runtime.ts
index b2308cca642f..16e31d2a7ec0 100644
--- a/src/process/supervisor/supervisor-log.runtime.ts
+++ b/src/process/supervisor/supervisor-log.runtime.ts
@@ -1,3 +1,4 @@
+// Supervisor log runtime bridges supervisor events into subsystem logging.
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 
 /** Runtime logging boundary for lazy supervisor paths and focused test mocks. */
diff --git a/src/process/supervisor/supervisor.pty-command.test.ts b/src/process/supervisor/supervisor.pty-command.test.ts
index 9743e9055b47..8110c1af128e 100644
--- a/src/process/supervisor/supervisor.pty-command.test.ts
+++ b/src/process/supervisor/supervisor.pty-command.test.ts
@@ -1,3 +1,4 @@
+// PTY command supervisor tests cover supervised terminal command lifecycles.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { createPtyAdapterMock } = vi.hoisted(() => ({
diff --git a/src/process/supervisor/supervisor.test.ts b/src/process/supervisor/supervisor.test.ts
index af9683e21f81..bba18d2d0df1 100644
--- a/src/process/supervisor/supervisor.test.ts
+++ b/src/process/supervisor/supervisor.test.ts
@@ -1,3 +1,4 @@
+// Process supervisor tests cover lifecycle, restart, and termination behavior.
 import { performance } from "node:perf_hooks";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { SpawnProcessAdapter } from "./types.js";
diff --git a/src/process/supervisor/supervisor.ts b/src/process/supervisor/supervisor.ts
index c99eeefe7394..6b9b55321881 100644
--- a/src/process/supervisor/supervisor.ts
+++ b/src/process/supervisor/supervisor.ts
@@ -1,3 +1,4 @@
+// Process supervisor manages long-running child and PTY process lifecycles.
 import crypto from "node:crypto";
 import { performance } from "node:perf_hooks";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/process/supervisor/types.ts b/src/process/supervisor/types.ts
index ce06299a5884..31efb76fac16 100644
--- a/src/process/supervisor/types.ts
+++ b/src/process/supervisor/types.ts
@@ -1,3 +1,4 @@
+// Process supervisor types describe supervised runs, states, and termination reasons.
 export type RunState = "starting" | "running" | "exiting" | "exited";
 
 export type TerminationReason =
diff --git a/src/process/windows-command.test.ts b/src/process/windows-command.test.ts
index d35ff0c3ba32..0dad9d29a417 100644
--- a/src/process/windows-command.test.ts
+++ b/src/process/windows-command.test.ts
@@ -1,3 +1,4 @@
+// Windows command tests cover command quoting and shell resolution on Windows.
 import { describe, expect, it } from "vitest";
 import { resolveWindowsCommandShim } from "./windows-command.js";
 
diff --git a/src/process/windows-command.ts b/src/process/windows-command.ts
index 29f014a6c8cf..3b0e81900c2b 100644
--- a/src/process/windows-command.ts
+++ b/src/process/windows-command.ts
@@ -1,3 +1,4 @@
+// Windows command helpers resolve executable and shell invocation details.
 import path from "node:path";
 import process from "node:process";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";