docs: document process helpers

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";
 

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";

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,

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";

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";

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";

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";

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";
 

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,

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";
 
 /**

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";
 

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";

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";
 

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";

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";

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,

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";

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";
 
 /**

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";
 

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";
 

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. */

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. */

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(() => ({

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";

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";

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 =

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";
 

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";