From b59b34f9d5775864f8fefb8544f07f5b88b7bc9e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 19:39:38 -0400
Subject: [PATCH] docs: document cli service tests

---
 src/cli/cron-cli/register.cron-edit.test.ts                      | 1 +
 src/cli/cron-cli/register.cron-simple.test.ts                    | 1 +
 src/cli/cron-cli/shared.cause-display.test.ts                    | 1 +
 src/cli/cron-cli/shared.test.ts                                  | 1 +
 src/cli/daemon-cli/gateway-token-drift.test.ts                   | 1 +
 src/cli/daemon-cli/install.integration.test.ts                   | 1 +
 src/cli/daemon-cli/install.test.ts                               | 1 +
 src/cli/daemon-cli/launchd-recovery.test.ts                      | 1 +
 src/cli/daemon-cli/lifecycle-core.config-guard.test.ts           | 1 +
 src/cli/daemon-cli/lifecycle-core.test.ts                        | 1 +
 src/cli/daemon-cli/lifecycle.test.ts                             | 1 +
 src/cli/daemon-cli/probe.test.ts                                 | 1 +
 src/cli/daemon-cli/register-service-commands.test.ts             | 1 +
 src/cli/daemon-cli/response.test.ts                              | 1 +
 src/cli/daemon-cli/restart-health.test.ts                        | 1 +
 src/cli/daemon-cli/shared.test.ts                                | 1 +
 src/cli/daemon-cli/status.gather.test.ts                         | 1 +
 src/cli/daemon-cli/status.print.test.ts                          | 1 +
 src/cli/daemon-cli/status.test.ts                                | 1 +
 src/cli/gateway-cli/qa-parent-watchdog.test.ts                   | 1 +
 src/cli/gateway-cli/register.option-collisions.test.ts           | 1 +
 src/cli/gateway-cli/run-loop.test.ts                             | 1 +
 src/cli/gateway-cli/run.option-collisions.test.ts                | 1 +
 src/cli/gateway-cli/run.supervised-lock.test.ts                  | 1 +
 src/cli/node-cli/daemon.test.ts                                  | 1 +
 src/cli/node-cli/register.test.ts                                | 1 +
 .../nodes-cli/register.invoke.approval-transport-timeout.test.ts | 1 +
 src/cli/send-runtime/channel-outbound-send.test.ts               | 1 +
 src/cli/shared/parse-port.test.ts                                | 1 +
 29 files changed, 29 insertions(+)

diff --git a/src/cli/cron-cli/register.cron-edit.test.ts b/src/cli/cron-cli/register.cron-edit.test.ts
index c420709deebb..5190bb191bcd 100644
--- a/src/cli/cron-cli/register.cron-edit.test.ts
+++ b/src/cli/cron-cli/register.cron-edit.test.ts
@@ -1,3 +1,4 @@
+// Cron edit register tests cover cron edit command registration and option wiring.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
diff --git a/src/cli/cron-cli/register.cron-simple.test.ts b/src/cli/cron-cli/register.cron-simple.test.ts
index 261cfee1adfb..3782f5af36f1 100644
--- a/src/cli/cron-cli/register.cron-simple.test.ts
+++ b/src/cli/cron-cli/register.cron-simple.test.ts
@@ -1,3 +1,4 @@
+// Cron simple register tests cover basic cron command registration and execution.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { CronJob } from "../../cron/types.js";
 import type { GatewayRpcOpts } from "../gateway-rpc.js";
diff --git a/src/cli/cron-cli/shared.cause-display.test.ts b/src/cli/cron-cli/shared.cause-display.test.ts
index a09695273d89..95de684cc9c1 100644
--- a/src/cli/cron-cli/shared.cause-display.test.ts
+++ b/src/cli/cron-cli/shared.cause-display.test.ts
@@ -1,3 +1,4 @@
+// Cron cause display tests cover cron error-cause formatting for users.
 import { describe, expect, it } from "vitest";
 import { defaultRuntime } from "../../runtime.js";
 import { printCronJson } from "./shared.js";
diff --git a/src/cli/cron-cli/shared.test.ts b/src/cli/cron-cli/shared.test.ts
index dc39b693ca94..d94d5d0271af 100644
--- a/src/cli/cron-cli/shared.test.ts
+++ b/src/cli/cron-cli/shared.test.ts
@@ -1,3 +1,4 @@
+// Cron shared tests cover shared cron CLI parsing, display, and error helpers.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { CronJob } from "../../cron/types.js";
 import type { RuntimeEnv } from "../../runtime.js";
diff --git a/src/cli/daemon-cli/gateway-token-drift.test.ts b/src/cli/daemon-cli/gateway-token-drift.test.ts
index 100f7931a761..9ee0b99fdb42 100644
--- a/src/cli/daemon-cli/gateway-token-drift.test.ts
+++ b/src/cli/daemon-cli/gateway-token-drift.test.ts
@@ -1,3 +1,4 @@
+// Gateway token drift tests cover daemon detection of gateway token/config mismatches.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import { resolveGatewayTokenForDriftCheck } from "./gateway-token-drift.js";
diff --git a/src/cli/daemon-cli/install.integration.test.ts b/src/cli/daemon-cli/install.integration.test.ts
index dc7a35859a8d..0f2dbca3402b 100644
--- a/src/cli/daemon-cli/install.integration.test.ts
+++ b/src/cli/daemon-cli/install.integration.test.ts
@@ -1,3 +1,4 @@
+// Daemon install integration tests cover service install paths with filesystem fixtures.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/cli/daemon-cli/install.test.ts b/src/cli/daemon-cli/install.test.ts
index 817f145b0b8c..266fdc8948df 100644
--- a/src/cli/daemon-cli/install.test.ts
+++ b/src/cli/daemon-cli/install.test.ts
@@ -1,3 +1,4 @@
+// Daemon install tests cover service install command behavior and plan handling.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ResolvedGatewayAuth } from "../../gateway/auth.js";
 import { captureFullEnv } from "../../test-utils/env.js";
diff --git a/src/cli/daemon-cli/launchd-recovery.test.ts b/src/cli/daemon-cli/launchd-recovery.test.ts
index 7b0aa8366149..4403f74a44e9 100644
--- a/src/cli/daemon-cli/launchd-recovery.test.ts
+++ b/src/cli/daemon-cli/launchd-recovery.test.ts
@@ -1,3 +1,4 @@
+// Launchd recovery tests cover daemon recovery behavior for macOS launchd services.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const launchAgentPlistExists = vi.hoisted(() => vi.fn());
diff --git a/src/cli/daemon-cli/lifecycle-core.config-guard.test.ts b/src/cli/daemon-cli/lifecycle-core.config-guard.test.ts
index 5361b7d6f1a4..465995f14d09 100644
--- a/src/cli/daemon-cli/lifecycle-core.config-guard.test.ts
+++ b/src/cli/daemon-cli/lifecycle-core.config-guard.test.ts
@@ -1,3 +1,4 @@
+// Daemon lifecycle config guard tests cover config checks before service lifecycle actions.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { VERSION } from "../../version.js";
 import {
diff --git a/src/cli/daemon-cli/lifecycle-core.test.ts b/src/cli/daemon-cli/lifecycle-core.test.ts
index 938e7de90c8c..ff70bfd2f3e4 100644
--- a/src/cli/daemon-cli/lifecycle-core.test.ts
+++ b/src/cli/daemon-cli/lifecycle-core.test.ts
@@ -1,3 +1,4 @@
+// Daemon lifecycle core tests cover service lifecycle transitions and platform adapters.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import {
diff --git a/src/cli/daemon-cli/lifecycle.test.ts b/src/cli/daemon-cli/lifecycle.test.ts
index b3ee50754b71..c279d49b35be 100644
--- a/src/cli/daemon-cli/lifecycle.test.ts
+++ b/src/cli/daemon-cli/lifecycle.test.ts
@@ -1,3 +1,4 @@
+// Daemon lifecycle tests cover CLI service lifecycle orchestration and cleanup.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { captureEnv } from "../../test-utils/env.js";
 
diff --git a/src/cli/daemon-cli/probe.test.ts b/src/cli/daemon-cli/probe.test.ts
index b93a81cab22c..9817cad0d754 100644
--- a/src/cli/daemon-cli/probe.test.ts
+++ b/src/cli/daemon-cli/probe.test.ts
@@ -1,3 +1,4 @@
+// Daemon probe tests cover gateway probe command behavior and output.
 import { describe, expect, it, vi } from "vitest";
 import { probeGatewayStatus } from "./probe.js";
 
diff --git a/src/cli/daemon-cli/register-service-commands.test.ts b/src/cli/daemon-cli/register-service-commands.test.ts
index 9e23f76af6ab..6f5217829d44 100644
--- a/src/cli/daemon-cli/register-service-commands.test.ts
+++ b/src/cli/daemon-cli/register-service-commands.test.ts
@@ -1,3 +1,4 @@
+// Register service command tests cover daemon service subcommand registration.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { addGatewayServiceCommands } from "./register-service-commands.js";
diff --git a/src/cli/daemon-cli/response.test.ts b/src/cli/daemon-cli/response.test.ts
index ba21cfb1911c..d38a20e90399 100644
--- a/src/cli/daemon-cli/response.test.ts
+++ b/src/cli/daemon-cli/response.test.ts
@@ -1,3 +1,4 @@
+// Daemon response tests cover normalized daemon command response shapes.
 import { describe, expect, it } from "vitest";
 import { buildDaemonHintItems } from "./response.js";
 
diff --git a/src/cli/daemon-cli/restart-health.test.ts b/src/cli/daemon-cli/restart-health.test.ts
index 4a838c528987..e3afcfa2c9d8 100644
--- a/src/cli/daemon-cli/restart-health.test.ts
+++ b/src/cli/daemon-cli/restart-health.test.ts
@@ -1,3 +1,4 @@
+// Daemon restart health tests cover health checks after daemon restart operations.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { GatewayService } from "../../daemon/service.js";
 import type { PortListenerKind, PortUsage } from "../../infra/ports.js";
diff --git a/src/cli/daemon-cli/shared.test.ts b/src/cli/daemon-cli/shared.test.ts
index 777365a67e93..353a762b1c05 100644
--- a/src/cli/daemon-cli/shared.test.ts
+++ b/src/cli/daemon-cli/shared.test.ts
@@ -1,3 +1,4 @@
+// Daemon shared tests cover shared daemon CLI helpers and validation.
 import { describe, expect, it } from "vitest";
 import { theme } from "../../../packages/terminal-core/src/theme.js";
 import {
diff --git a/src/cli/daemon-cli/status.gather.test.ts b/src/cli/daemon-cli/status.gather.test.ts
index f8e3d53a93a9..ea7365658a2f 100644
--- a/src/cli/daemon-cli/status.gather.test.ts
+++ b/src/cli/daemon-cli/status.gather.test.ts
@@ -1,3 +1,4 @@
+// Daemon status gather tests cover service status collection from platform state.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/cli/daemon-cli/status.print.test.ts b/src/cli/daemon-cli/status.print.test.ts
index 24f7f988b60e..558c15742117 100644
--- a/src/cli/daemon-cli/status.print.test.ts
+++ b/src/cli/daemon-cli/status.print.test.ts
@@ -1,3 +1,4 @@
+// Daemon status print tests cover user-facing service status formatting.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { formatCliCommand } from "../command-format.js";
 import { printDaemonStatus } from "./status.print.js";
diff --git a/src/cli/daemon-cli/status.test.ts b/src/cli/daemon-cli/status.test.ts
index 352c31bc7540..d5404d1796f0 100644
--- a/src/cli/daemon-cli/status.test.ts
+++ b/src/cli/daemon-cli/status.test.ts
@@ -1,3 +1,4 @@
+// Daemon status tests cover service status gathering and CLI responses.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createCliRuntimeCapture } from "../test-runtime-capture.js";
 import type { DaemonStatus } from "./status.gather.js";
diff --git a/src/cli/gateway-cli/qa-parent-watchdog.test.ts b/src/cli/gateway-cli/qa-parent-watchdog.test.ts
index 52569a119610..4cb5c5db778f 100644
--- a/src/cli/gateway-cli/qa-parent-watchdog.test.ts
+++ b/src/cli/gateway-cli/qa-parent-watchdog.test.ts
@@ -1,3 +1,4 @@
+// Gateway QA parent watchdog tests cover parent-process watchdog shutdown behavior.
 import { describe, expect, it, vi } from "vitest";
 import {
   installQaParentWatchdog,
diff --git a/src/cli/gateway-cli/register.option-collisions.test.ts b/src/cli/gateway-cli/register.option-collisions.test.ts
index a9cf90c25a98..ac99d5a79d6e 100644
--- a/src/cli/gateway-cli/register.option-collisions.test.ts
+++ b/src/cli/gateway-cli/register.option-collisions.test.ts
@@ -1,3 +1,4 @@
+// Gateway register option collision tests cover gateway command option registration.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { registerGatewayCli } from "./register.js";
diff --git a/src/cli/gateway-cli/run-loop.test.ts b/src/cli/gateway-cli/run-loop.test.ts
index b7aca7e6e0a7..630b7e649fa5 100644
--- a/src/cli/gateway-cli/run-loop.test.ts
+++ b/src/cli/gateway-cli/run-loop.test.ts
@@ -1,3 +1,4 @@
+// Gateway run loop tests cover foreground gateway lifecycle and restart behavior.
 import { describe, expect, it, vi } from "vitest";
 import type { GatewayServer } from "../../gateway/server.impl.js";
 import type { GatewayBonjourBeacon } from "../../infra/bonjour-discovery.js";
diff --git a/src/cli/gateway-cli/run.option-collisions.test.ts b/src/cli/gateway-cli/run.option-collisions.test.ts
index ed85f59039a6..36e577861dfb 100644
--- a/src/cli/gateway-cli/run.option-collisions.test.ts
+++ b/src/cli/gateway-cli/run.option-collisions.test.ts
@@ -1,3 +1,4 @@
+// Gateway run option collision tests cover gateway run flag registration boundaries.
 import path from "node:path";
 import { Command } from "commander";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/cli/gateway-cli/run.supervised-lock.test.ts b/src/cli/gateway-cli/run.supervised-lock.test.ts
index cd68578c6960..3a93f365e7fe 100644
--- a/src/cli/gateway-cli/run.supervised-lock.test.ts
+++ b/src/cli/gateway-cli/run.supervised-lock.test.ts
@@ -1,3 +1,4 @@
+// Gateway supervised lock tests cover single-runner locking for supervised gateway starts.
 import { describe, expect, it, vi } from "vitest";
 import { GatewayLockError } from "../../infra/gateway-lock.js";
 import { testing } from "./run.js";
diff --git a/src/cli/node-cli/daemon.test.ts b/src/cli/node-cli/daemon.test.ts
index 86967f89a73e..3d95182b01a0 100644
--- a/src/cli/node-cli/daemon.test.ts
+++ b/src/cli/node-cli/daemon.test.ts
@@ -1,3 +1,4 @@
+// Node daemon tests cover node daemon command runtime behavior and errors.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { GatewayServiceRuntime } from "../../daemon/service-runtime.js";
 import { runNodeDaemonStatus } from "./daemon.js";
diff --git a/src/cli/node-cli/register.test.ts b/src/cli/node-cli/register.test.ts
index 86fcea65523b..36a9031c9fb7 100644
--- a/src/cli/node-cli/register.test.ts
+++ b/src/cli/node-cli/register.test.ts
@@ -1,3 +1,4 @@
+// Node CLI register tests cover node command registration and option wiring.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { registerNodeCli } from "./register.js";
diff --git a/src/cli/nodes-cli/register.invoke.approval-transport-timeout.test.ts b/src/cli/nodes-cli/register.invoke.approval-transport-timeout.test.ts
index e7f388eca948..ff905a40b9e3 100644
--- a/src/cli/nodes-cli/register.invoke.approval-transport-timeout.test.ts
+++ b/src/cli/nodes-cli/register.invoke.approval-transport-timeout.test.ts
@@ -1,3 +1,4 @@
+// Node invoke approval timeout tests cover approval transport timeout handling.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { DEFAULT_EXEC_APPROVAL_TIMEOUT_MS } from "../../infra/exec-approvals.js";
 import { parseTimeoutMs } from "../parse-timeout.js";
diff --git a/src/cli/send-runtime/channel-outbound-send.test.ts b/src/cli/send-runtime/channel-outbound-send.test.ts
index a729f57dd0e7..fce629c480de 100644
--- a/src/cli/send-runtime/channel-outbound-send.test.ts
+++ b/src/cli/send-runtime/channel-outbound-send.test.ts
@@ -1,3 +1,4 @@
+// Channel outbound send tests cover CLI send runtime handoff to channel outbound adapters.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
diff --git a/src/cli/shared/parse-port.test.ts b/src/cli/shared/parse-port.test.ts
index 9418278d1f52..ca7bc1b4398d 100644
--- a/src/cli/shared/parse-port.test.ts
+++ b/src/cli/shared/parse-port.test.ts
@@ -1,3 +1,4 @@
+// Parse port tests cover shared CLI port parsing and validation.
 import { describe, expect, it } from "vitest";
 import { parsePort } from "./parse-port.js";