docs: document doctor session checks

steipete · steipete · commit c0b3c8cdb9dc · 2026-06-04T12:08:24.000-04:00
diff --git a/src/commands/doctor-session-locks.ts b/src/commands/doctor-session-locks.ts
@@ -1,3 +1,4 @@
+/** Doctor diagnostics and cleanup for stale session write lock files. */
 import { note } from "../../packages/terminal-core/src/note.js";
 import { resolveAgentSessionDirs } from "../agents/session-dirs.js";
 import {
@@ -39,6 +40,7 @@ function formatLockLine(lock: SessionLockInspection): string {
   return `- ${shortenHomePath(lock.lockPath)} ${pidStatus} ${ageStatus} ${staleStatus}${removedStatus}`;
 }
 
+/** Reports session write locks and removes stale locks when doctor repair is enabled. */
 export async function noteSessionLockHealth(params?: {
   shouldRepair?: boolean;
   config?: SessionWriteLockAcquireTimeoutConfig;
diff --git a/src/commands/doctor-session-snapshots.ts b/src/commands/doctor-session-snapshots.ts
@@ -1,3 +1,4 @@
+/** Doctor repair for stale runtime snapshot paths cached in session stores. */
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -201,6 +202,7 @@ function resolveExpectedBundledSkillPath(params: {
   return params.pathExists(expectedPath) ? expectedPath : undefined;
 }
 
+/** Finds cached bundled-skill paths that point at old runtime/temp package roots. */
 export function scanSessionStoreForStaleRuntimeSnapshotPaths(params: {
   store: Record<string, SessionEntry>;
   bundledSkillsDir: string | undefined;
@@ -284,10 +286,7 @@ function loadSessionStoreForSnapshotScan(storePath: string): Record<string, Sess
   return store;
 }
 
-/**
- * Replace stale paths in raw text content (blob files or inline prompts).
- * Handles raw, JSON-escaped, and XML-escaped forms.
- */
+/** Replaces stale paths in raw, JSON-escaped, and XML-escaped prompt text. */
 function replaceStalePathsInText(text: string, finding: StaleSessionSnapshotPathFinding): string {
   const jsonEscaped = JSON.stringify(finding.cachedPath).slice(1, -1);
   const jsonEscapedExpected = JSON.stringify(finding.expectedPath).slice(1, -1);
@@ -317,6 +316,7 @@ function replaceStalePathsInText(text: string, finding: StaleSessionSnapshotPath
   return result;
 }
 
+/** Reports and optionally repairs stale bundled skill paths in session snapshot metadata. */
 export async function noteSessionSnapshotHealth(params?: {
   storePaths?: string[];
   bundledSkillsDir?: string;
@@ -366,7 +366,6 @@ export async function noteSessionSnapshotHealth(params?: {
     ),
   );
 
-  // Auto-repair stale paths when shouldRepair is enabled
   if (params?.shouldRepair) {
     let repairedStores = 0;
     let totalReplacements = 0;
diff --git a/src/commands/doctor-session-state-providers.ts b/src/commands/doctor-session-state-providers.ts
@@ -1,3 +1,4 @@
+/** Doctor repair for stale plugin-owned routing state persisted in session entries. */
 import { normalizeOptionalString as normalizeString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeStringEntriesLower } from "@openclaw/normalization-core/string-normalization";
 import { note } from "../../packages/terminal-core/src/note.js";
@@ -58,6 +59,7 @@ function resolveSessionAgentId(cfg: OpenClawConfig, sessionKey: string): string
   return parseAgentSessionKey(sessionKey)?.agentId ?? resolveDefaultAgentId(cfg);
 }
 
+/** Resolves the currently configured provider/model/runtime route for a session key. */
 export function resolveConfiguredDoctorSessionStateRoute(params: {
   cfg: OpenClawConfig;
   sessionKey: string;
@@ -121,6 +123,7 @@ function entryMayContainPluginSessionRouteState(entry: SessionEntry): boolean {
   );
 }
 
+/** Fast prefilter for session stores that might contain plugin-owned routing state. */
 export function storeMayContainPluginSessionRouteState(
   store: Record<string, SessionEntry>,
 ): boolean {
@@ -328,6 +331,7 @@ function scanEntryForOwner(params: {
   };
 }
 
+/** Scans session entries for state owned by plugins that no longer match the configured route. */
 export function scanSessionRouteStateOwners(params: {
   owners: readonly DoctorSessionRouteStateOwner[];
   store: Record<string, Record<string, unknown>>;
@@ -386,6 +390,7 @@ function clearRecordKeys(
   return true;
 }
 
+/** Clears stale plugin-owned routing fields from a session entry and refreshes updatedAt. */
 export function applySessionRouteStateRepair(params: {
   entry: Record<string, unknown>;
   repair: DoctorSessionRouteStateRepair;
@@ -443,6 +448,7 @@ function groupRepairsByOwner(
   return grouped;
 }
 
+/** Prompts for and applies plugin-owned session route state repairs to the session store. */
 export async function runPluginSessionStateDoctorRepairs(params: {
   cfg: OpenClawConfig;
   store: Record<string, SessionEntry>;
diff --git a/src/commands/doctor-session-transcripts.ts b/src/commands/doctor-session-transcripts.ts
@@ -1,3 +1,4 @@
+/** Doctor repair for broken session transcript branches and legacy OpenAI Codex metadata. */
 import type { Dirent } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -208,6 +209,7 @@ async function writeTranscriptEntries(params: {
   return backupPath;
 }
 
+/** Repairs one transcript file by keeping the active branch and backing up the original file. */
 export async function repairBrokenSessionTranscriptFile(params: {
   filePath: string;
   shouldRepair: boolean;
@@ -309,6 +311,7 @@ async function listSessionTranscriptFiles(sessionDirs: string[]): Promise<string
   return files.toSorted((a, b) => a.localeCompare(b));
 }
 
+/** Scans session transcript files and reports or repairs legacy/broken transcript state. */
 export async function noteSessionTranscriptHealth(params?: {
   shouldRepair?: boolean;
   sessionDirs?: string[];
diff --git a/src/commands/doctor-skills-core.ts b/src/commands/doctor-skills-core.ts
@@ -1,6 +1,8 @@
+/** Pure helpers for doctor skill readiness repairs. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { SkillStatusEntry, SkillStatusReport } from "../skills/discovery/status.js";
 
+/** Returns allowed skills that are unusable in the current runtime environment. */
 export function collectUnavailableAgentSkills(report: SkillStatusReport): SkillStatusEntry[] {
   return report.skills.filter(
     (skill) =>
@@ -11,6 +13,7 @@ export function collectUnavailableAgentSkills(report: SkillStatusReport): SkillS
   );
 }
 
+/** Disables unavailable skills in config while preserving existing skill entries. */
 export function disableUnavailableSkillsInConfig(
   config: OpenClawConfig,
   skills: readonly SkillStatusEntry[],
diff --git a/src/commands/doctor-skills.ts b/src/commands/doctor-skills.ts
@@ -1,3 +1,4 @@
+/** Doctor checks and repair prompts for unavailable configured skills. */
 import { existsSync } from "node:fs";
 import { note } from "../../packages/terminal-core/src/note.js";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
@@ -57,10 +58,12 @@ function defaultGhConfigDiscoveryInput(): GhConfigDiscoveryInput {
   };
 }
 
+/** Builds a GitHub CLI config-dir hint for eligible GitHub skill setups. */
 export function describeGhConfigDirHint(skills: SkillStatusEntry[]): string[] {
   return describeGhConfigDirHintFromDiscovery(skills, defaultGhConfigDiscoveryInput());
 }
 
+/** Builds a GitHub CLI config-dir hint from injected discovery inputs for tests. */
 export function describeGhConfigDirHintFromDiscovery(
   skills: SkillStatusEntry[],
   discoveryInput: GhConfigDiscoveryInput,
@@ -84,6 +87,7 @@ export function describeGhConfigDirHintFromDiscovery(
   return formatGhConfigDirMismatchHint(result);
 }
 
+/** Formats doctor note lines for skills that are allowed but unavailable. */
 export function formatUnavailableSkillDoctorLines(skills: SkillStatusEntry[]): string[] {
   const lines: string[] = [
     "Some skills are allowed for this agent but are not usable in the current runtime environment.",
@@ -99,6 +103,7 @@ export function formatUnavailableSkillDoctorLines(skills: SkillStatusEntry[]): s
   return lines;
 }
 
+/** Checks default-agent skill readiness and optionally disables unavailable skills in config. */
 export async function maybeRepairSkillReadiness(params: {
   cfg: OpenClawConfig;
   prompter: DoctorPrompter;
