docs: document process helpers

steipete · steipete · commit a628a66e4d1e · 2026-06-04T20:14:34.000-04:00
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Child process bridge adapts child process events into typed lifecycle callbacks.`
`1`	`2`	`import type { ChildProcess } from "node:child_process";`
`2`	`3`	`import process from "node:process";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Command queue tests cover bounded command execution and queue ordering.`
`1`	`2`	`import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";`
`2`	`3`	`import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
`3`	`4`	`import { CommandLane } from "./lanes.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Command queue serializes and limits process execution for shared command lanes.`
`1`	`2`	`import {`
`2`	`3`	`diagnosticLogger as diag,`
`3`	`4`	`logLaneDequeue,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// No-output timer tests cover idle command timeout and output reset behavior.`
`1`	`2`	`import type { ChildProcess } from "node:child_process";`
`2`	`3`	`import { EventEmitter } from "node:events";`
`3`	`4`	`import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Exec tests cover command execution, output capture, and cancellation behavior.`
`1`	`2`	`import type { ChildProcess } from "node:child_process";`
`2`	`3`	`import { EventEmitter } from "node:events";`
`3`	`4`	`import process from "node:process";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Exec helpers run subprocesses with normalized output, timeout, and abort handling.`
`1`	`2`	`import { execFile, spawn } from "node:child_process";`
`2`	`3`	`import fs from "node:fs";`
`3`	`4`	`import path from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Windows exec tests cover command invocation behavior on Windows paths.`
`1`	`2`	`import type { execFile as execFileType } from "node:child_process";`
`2`	`3`	`import { EventEmitter } from "node:events";`
`3`	`4`	`import fs from "node:fs";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Kill tree tests cover process tree termination and platform-specific fallbacks.`
`1`	`2`	`import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { withMockedPlatform } from "../test-utils/vitest-spies.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Linux OOM score tests cover best-effort process OOM score adjustment.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`hardenedEnvForChildOomWrap,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Linux OOM score helpers adjust child process OOM priority when supported.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`
`3`	`4`	`/**`