docs: document task command helpers

steipete · steipete · commit 8d65e78a071e · 2026-06-04T13:17:07.000-04:00
diff --git a/src/commands/systemd-linger.ts b/src/commands/systemd-linger.ts
@@ -1,3 +1,6 @@
+// Systemd lingering setup helpers for gateway install/start flows.
+// Lingering keeps user services alive after logout on Linux hosts.
+
 import { note } from "../../packages/terminal-core/src/note.js";
 import {
   enableSystemdUserLinger,
@@ -11,6 +14,7 @@ export type LingerPrompter = {
   note: (message: string, title?: string) => Promise<void> | void;
 };
 
+/** Ensures systemd user lingering interactively, prompting before sudo when requested. */
 export async function ensureSystemdUserLingerInteractive(params: {
   runtime: RuntimeEnv;
   prompter?: LingerPrompter;
@@ -89,6 +93,7 @@ export async function ensureSystemdUserLingerInteractive(params: {
   await prompter.note(`Run manually: sudo loginctl enable-linger ${status.user}`, title);
 }
 
+/** Best-effort non-interactive lingering enablement for install scripts and CI-like flows. */
 export async function ensureSystemdUserLingerNonInteractive(params: {
   runtime: RuntimeEnv;
   env?: NodeJS.ProcessEnv;
diff --git a/src/commands/tasks-audit-system.ts b/src/commands/tasks-audit-system.ts
@@ -1,3 +1,6 @@
+// Combines task and task-flow audit findings for CLI output.
+// The combined shape lets list/json commands filter and sort both registries together.
+
 import type {
   TaskFlowAuditCode,
   TaskFlowAuditFinding,
@@ -44,6 +47,7 @@ function compareSystemAuditFindings(left: TaskSystemAuditFinding, right: TaskSys
   );
 }
 
+/** Builds combined task/task-flow audit findings with optional severity/code filtering. */
 export function buildTaskSystemAuditFindings(params: {
   taskFindings: TaskAuditFinding[];
   flowFindings: TaskFlowAuditFinding[];
@@ -83,6 +87,7 @@ export function buildTaskSystemAuditFindings(params: {
       return true;
     })
     .toSorted(compareSystemAuditFindings);
+  // Keep summary counts based on the full sorted set; filters only affect displayed findings.
   const sortedAllFindings = [...allFindings].toSorted(compareSystemAuditFindings);
   return {
     allFindings: sortedAllFindings,
diff --git a/src/commands/tasks-json.ts b/src/commands/tasks-json.ts
@@ -1,12 +1,12 @@
+// JSON-only task command helpers.
+// These paths avoid maintenance reconciliation so short-lived JSON CLI processes stay read-only and exit cleanly.
+
 import type { RuntimeEnv } from "../runtime.js";
 import { writeRuntimeJson } from "../runtime.js";
 import { listTaskRecords } from "../tasks/runtime-internal.js";
 import { listTaskFlowAuditFindings } from "../tasks/task-flow-registry.audit.js";
 import { listTaskFlowRecords } from "../tasks/task-flow-runtime-internal.js";
-import {
-  listTaskAuditFindings,
-  summarizeTaskAuditFindings,
-} from "../tasks/task-registry.audit.js";
+import { listTaskAuditFindings, summarizeTaskAuditFindings } from "../tasks/task-registry.audit.js";
 import type { TaskRecord } from "../tasks/task-registry.types.js";
 import {
   buildTaskSystemAuditFindings,
@@ -79,6 +79,7 @@ function buildTasksAuditJsonPayload(opts: TasksAuditJsonArgs) {
   });
   const limit = typeof opts.limit === "number" && opts.limit > 0 ? opts.limit : undefined;
   const displayed = limit ? filteredFindings.slice(0, limit) : filteredFindings;
+  // Preserve the legacy task-only summary while adding combined task-flow counts.
   const legacySummary = summarizeTaskAuditFindings(taskFindings);
   return {
     count: allFindings.length,
@@ -102,13 +103,15 @@ function buildTasksAuditJsonPayload(opts: TasksAuditJsonArgs) {
   };
 }
 
+/** Writes task list JSON without triggering task maintenance. */
 export async function tasksListJsonCommand(
   opts: TasksListJsonArgs,
   runtime: RuntimeEnv,
 ): Promise<void> {
   writeRuntimeJson(runtime, buildTasksListJsonPayload(opts));
 }
 
+/** Writes task audit JSON with combined task/task-flow findings. */
 export async function tasksAuditJsonCommand(
   opts: TasksAuditJsonArgs,
   runtime: RuntimeEnv,
diff --git a/src/commands/tasks.ts b/src/commands/tasks.ts
@@ -1,3 +1,6 @@
+// Human-facing background task commands.
+// Handles task listing/show/cancel/notify/audit plus registry maintenance for tasks, flows, and sessions.
+
 import fs from "node:fs";
 import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -129,6 +132,7 @@ function buildSessionRegistryPreserveKeys(params: {
   for (const key of Object.keys(params.store)) {
     const jobId = parseCronRunSessionJobId(key);
     if (!jobId) {
+      // Non-cron session rows are outside this maintenance pass; preserve them.
       preserveKeys.add(key);
       continue;
     }
@@ -161,6 +165,7 @@ async function runSessionRegistryMaintenance(params: {
     const beforeStore = loadSessionStore(target.storePath, { skipCache: true });
     const beforeCount = Object.keys(beforeStore).length;
     if (params.apply) {
+      // Apply mode mutates each store atomically through updateSessionStore.
       const applied = await updateSessionStore(
         target.storePath,
         (store) => {
@@ -191,6 +196,7 @@ async function runSessionRegistryMaintenance(params: {
       continue;
     }
     const previewStore = structuredClone(beforeStore);
+    // Preview mode runs pruning against a clone so dry-run output cannot change stores.
     const { preserveKeys, preservedRunning } = buildSessionRegistryPreserveKeys({
       store: previewStore,
       runningCronJobIds,
@@ -350,6 +356,7 @@ function toSystemAuditFindings(params: {
   severityFilter?: TaskSystemAuditSeverity;
   codeFilter?: TaskSystemAuditCode;
 }) {
+  // Human audit reconciles inspectable tasks first so stale detached runs are reflected.
   const taskFindings = listTaskAuditFindings({ tasks: reconcileInspectableTasks() });
   const flowFindings = listTaskFlowAuditFindings();
   return buildTaskSystemAuditFindings({
@@ -360,6 +367,7 @@ function toSystemAuditFindings(params: {
   });
 }
 
+/** Lists background tasks with optional runtime/status filters. */
 export async function tasksListCommand(
   opts: { json?: boolean; runtime?: string; status?: string },
   runtime: RuntimeEnv,
@@ -412,6 +420,7 @@ export async function tasksListCommand(
   }
 }
 
+/** Shows one task record by id or lookup token. */
 export async function tasksShowCommand(
   opts: { json?: boolean; lookup: string },
   runtime: RuntimeEnv,
@@ -458,6 +467,7 @@ export async function tasksShowCommand(
   }
 }
 
+/** Updates a task's notification policy. */
 export async function tasksNotifyCommand(
   opts: { lookup: string; notify: TaskNotifyPolicy },
   runtime: RuntimeEnv,
@@ -480,6 +490,7 @@ export async function tasksNotifyCommand(
   runtime.log(`Updated ${updated.taskId} notify policy to ${updated.notifyPolicy}.`);
 }
 
+/** Cancels a detached task run by lookup token. */
 export async function tasksCancelCommand(opts: { lookup: string }, runtime: RuntimeEnv) {
   const task = reconcileTaskLookupToken(opts.lookup);
   if (!task) {
@@ -507,6 +518,7 @@ export async function tasksCancelCommand(opts: { lookup: string }, runtime: Runt
   );
 }
 
+/** Prints or serializes combined task/task-flow audit findings. */
 export async function tasksAuditCommand(
   opts: {
     json?: boolean;
@@ -587,6 +599,7 @@ export async function tasksAuditCommand(
   }
 }
 
+/** Previews or applies task, task-flow, and backing session-registry maintenance. */
 export async function tasksMaintenanceCommand(
   opts: { json?: boolean; apply?: boolean },
   runtime: RuntimeEnv,
