docs: document status command wiring

src/commands/status.command.text-runtime.ts

@@ -1,3 +1,6 @@
+// Text-mode status runtime barrel.
+// Kept separate from command orchestration so JSON/fast status does not import table/theme helpers.
+
 export { formatCliCommand } from "../cli/command-format.js";
 export { info } from "../globals.js";
 export { formatTimeAgo } from "../infra/format-time/format-relative.ts";

src/commands/status.command.ts

@@ -1,3 +1,6 @@
+// Main `openclaw status` command orchestrator.
+// It routes all/json/deep modes, collects scan/runtime state, and delegates formatting to report builders.
+
 import {
   normalizePairingConnectRequestId,
   readConnectPairingRequiredMessage,
@@ -53,6 +56,7 @@ function loadStatusNodeModeModule() {
   return statusNodeModeModuleLoader.load();
 }
 
+/** Extracts device-pairing recovery context from structured gateway errors or legacy message text. */
 export function resolvePairingRecoveryContext(params: {
   error?: string | null;
   closeReason?: string | null;
@@ -72,6 +76,7 @@ export function resolvePairingRecoveryContext(params: {
         : null,
     };
   }
+  // Older gateways only exposed pairing details in close/error text; keep status recovery helpful there.
   const source = [params.error, params.closeReason]
     .filter((part) => typeof part === "string" && part.trim().length > 0)
     .join(" ");
@@ -86,6 +91,7 @@ export function resolvePairingRecoveryContext(params: {
   };
 }
 
+/** Runs `openclaw status`, including JSON/all routing and optional deep probes. */
 export async function statusCommand(
   opts: {
     json?: boolean;
@@ -98,6 +104,7 @@ export async function statusCommand(
   runtime: RuntimeEnv,
 ) {
   if (opts.all && !opts.json) {
+    // Human `--all` has a dedicated report path; JSON `--all` stays on the JSON schema.
     await loadStatusAllModule().then(({ statusAllCommand }) =>
       statusAllCommand(runtime, { timeoutMs: opts.timeoutMs }),
     );
@@ -221,6 +228,7 @@ export async function statusCommand(
   });
 
   if (opts.verbose) {
+    // Verbose status prints the raw gateway target resolution before the report tables.
     const { buildGatewayConnectionDetails } = await import("../gateway/call.js");
     const details = buildGatewayConnectionDetails({ config: scan.cfg });
     logGatewayConnectionDetails({
@@ -234,6 +242,7 @@ export async function statusCommand(
   const tableWidth = getTerminalTableWidth();
 
   if (secretDiagnostics.length > 0) {
+    // Secret diagnostics are already redacted by the scanner; show them before the main report.
     runtime.log(theme.warn("Secret diagnostics:"));
     for (const entry of secretDiagnostics) {
       runtime.log(`- ${entry}`);

src/commands/status.daemon.ts

@@ -1,3 +1,6 @@
+// Daemon service summary helpers for status output.
+// Gateway and node service state share the same normalized shape.
+
 import { resolveNodeService } from "../daemon/node-service.js";
 import { resolveGatewayService } from "../daemon/service.js";
 import { formatDaemonRuntimeShort } from "./status.format.js";
@@ -34,10 +37,12 @@ async function buildDaemonStatusSummary(
   };
 }
 
+/** Returns the gateway daemon status summary. */
 export async function getDaemonStatusSummary(): Promise<DaemonStatusSummary> {
   return await buildDaemonStatusSummary("gateway");
 }
 
+/** Returns the node service status summary. */
 export async function getNodeDaemonStatusSummary(): Promise<DaemonStatusSummary> {
   return await buildDaemonStatusSummary("node");
 }

src/commands/status.format.ts

@@ -1,3 +1,6 @@
+// Formatting helpers for status tokens, durations, prompt-cache stats, and daemon runtime snippets.
+// These helpers are shared by report rows and command output surfaces.
+
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { getSystemdCgroupHygieneSummary } from "../daemon/service-runtime.js";
 import { formatDurationPrecise } from "../infra/format-time/format-duration.ts";
@@ -5,9 +8,11 @@ import { formatRuntimeStatusWithDetails } from "../infra/runtime-status.ts";
 import type { SessionStatus } from "./status.types.js";
 export { shortenText } from "./text-format.js";
 
+/** Formats a token count in thousands for compact status rows. */
 export const formatKTokens = (value: number) =>
   `${(value / 1000).toFixed(value >= 10_000 ? 0 : 1)}k`;
 
+/** Formats a duration or returns `unknown` for missing/non-finite values. */
 export const formatDuration = (ms: number | null | undefined) => {
   if (ms == null || !Number.isFinite(ms)) {
     return "unknown";
@@ -15,6 +20,7 @@ export const formatDuration = (ms: number | null | undefined) => {
   return formatDurationPrecise(ms, { decimals: 1 });
 };
 
+/** Formats session token usage and prompt-cache hit rate for the sessions table. */
 export const formatTokensCompact = (
   sess: Pick<
     SessionStatus,
@@ -42,6 +48,7 @@ export const formatTokensCompact = (
   return result;
 };
 
+/** Formats prompt-cache details for verbose sessions table output. */
 export const formatPromptCacheCompact = (
   sess: Pick<SessionStatus, "inputTokens" | "totalTokens" | "cacheRead" | "cacheWrite">,
 ) => {
@@ -98,6 +105,7 @@ function resolvePromptCacheStats(
   };
 }
 
+/** Formats daemon runtime status plus launchd/systemd details into one compact string. */
 export const formatDaemonRuntimeShort = (runtime?: {
   status?: string;
   pid?: number;
@@ -114,6 +122,7 @@ export const formatDaemonRuntimeShort = (runtime?: {
   const noisyLaunchctlDetail =
     runtime.missingUnit === true &&
     normalizeLowercaseStringOrEmpty(detail).includes("could not find service");
+  // launchctl reports missing units noisily; installed=false already carries that signal.
   if (detail && !noisyLaunchctlDetail) {
     details.push(detail);
   }

src/commands/status.gateway-connection.ts

@@ -1,7 +1,11 @@
+// Gateway connection detail formatting for status reports.
+// Keeps verbose human text and status-all connection sections consistent.
+
 import type { RuntimeEnv } from "../runtime.js";
 import type { NodeOnlyGatewayInfo } from "./status.node-mode.js";
 import type { StatusScanOverviewResult } from "./status.scan-overview.ts";
 
+/** Logs multi-line gateway connection details with the standard heading. */
 export function logGatewayConnectionDetails(params: {
   runtime: Pick<RuntimeEnv, "log">;
   info: (value: string) => string;
@@ -17,6 +21,7 @@ export function logGatewayConnectionDetails(params: {
   }
 }
 
+/** Builds status-all gateway connection details, including remote-url fallback diagnostics. */
 export function resolveStatusAllConnectionDetails(params: {
   nodeOnlyGateway: NodeOnlyGatewayInfo | null;
   remoteUrlMissing: boolean;
@@ -30,6 +35,7 @@ export function resolveStatusAllConnectionDetails(params: {
   if (!params.remoteUrlMissing) {
     return params.gatewayConnection.message;
   }
+  // Remote mode without a URL probes local fallback only so the report can still diagnose config.
   return [
     "Gateway mode: remote",
     "Gateway target: (missing gateway.remote.url)",